# Spin up ephemeral databases for scratch work

Source: https://www.hotdata.dev/use-cases/sql-sandboxes
Site index: https://www.hotdata.dev/llms.txt

Exploratory SQL is easier when you're not leaning on shared prod or a crowded staging schema. Create a throwaway instant database with an expiry, load and query in isolation, then let it disappear — no cleanup, no stepping on teammates or shared quotas.

## How it works

### Step 1: Create an ephemeral database

**Claude**

```
Spin up a throwaway database called scratch that auto-expires in 24 hours, so my experiments don’t linger.
```

**CLI**

```bash
hotdata databases create --catalog scratch --name "Staging validation" --expires-at 24h
```

**Python SDK**

```python
import hotdata

db_api = hotdata.DatabasesApi(api_client)
db_api.create_database(
    hotdata.CreateDatabaseRequest(
        name="Staging validation",
        default_catalog="scratch",
        expires_at="24h",
    )
)
```

### Step 2: Explore and query

**Claude**

```
Show the columns on our product analytics data source, then give me event counts by week for the last 24 weeks from the events table.
```

**CLI**

```bash
hotdata databases tables list
hotdata query "SELECT date_trunc('week', created_at), COUNT(*) FROM analytics.public.events GROUP BY 1 LIMIT 24"
```

**Python SDK**

```python
import hotdata

query_api = hotdata.QueryApi(api_client)
query_api.query(
    hotdata.QueryRequest(
        sql=(
            "SELECT date_trunc('week', created_at), COUNT(*) "
            "FROM analytics.public.events GROUP BY 1 LIMIT 24"
        ),
    ),
)
```

### Step 3: Load a one-off file into it

**Claude**

```
Load segment.parquet as a high_value_users table in my scratch database. What table name do I query afterward?
```

**CLI**

```bash
hotdata databases load --catalog scratch --table high_value_users --file ./segment.parquet
```

**Python SDK**

```python
import hotdata

uploads = hotdata.UploadsApi(api_client)
with open("segment.parquet", "rb") as f:
    up = uploads.upload_file(f.read())
conn_api = hotdata.ConnectionsApi(api_client)
conn_api.load_managed_table(
    "<db.default_connection_id>", "public", "high_value_users",
    hotdata.LoadManagedTableRequest(mode="replace", upload_id=up.upload_id),
)
# Query as: SELECT * FROM scratch.public.high_value_users
```

### Step 4: Point the rest of your session at the sandbox

`databases use` makes a database the default target for later commands, so one-off exploration lands in the throwaway instead of a shared database. It takes the database id that `create` prints. Combined with `--expires-at` at create time, the sandbox cleans itself up.

**Claude**

```
Create a throwaway database for a one-off exploration, make it my default so my next queries land there, and let it auto-expire.
```

**CLI**

```bash
hotdata databases create --catalog exploration --name "API exploration" --expires-at 24h
# databases use takes the id printed by create
hotdata databases use <database_id>
hotdata query "SELECT 1"
```

**Python SDK**

```python
import hotdata

db_api = hotdata.DatabasesApi(api_client)
db = db_api.create_database(
    hotdata.CreateDatabaseRequest(
        name="API exploration",
        default_catalog="exploration",
        expires_at="24h",
    )
)
query_api = hotdata.QueryApi(api_client)
query_api.query(hotdata.QueryRequest(sql="SELECT 1"), x_database_id=db.id)
```

### Step 5: Isolate messy uploads in their own throwaway database

**Claude**

```
I’m loading a rough partner extract for a one-off QA join. Keep it in a throwaway database that expires so it doesn’t linger after we’re done.
```

**CLI**

```bash
hotdata databases create --catalog qa --expires-at 24h
hotdata databases load --catalog qa --table partner_extract --file ./partner_extract.parquet
```

**Python SDK**

```python
import hotdata

db_api = hotdata.DatabasesApi(api_client)
db = db_api.create_database(
    hotdata.CreateDatabaseRequest(
        name="Partner extract QA",
        default_catalog="qa",
        expires_at="24h",
    )
)
uploads = hotdata.UploadsApi(api_client)
with open("partner_extract.parquet", "rb") as f:
    up = uploads.upload_file(f.read())
conn_api = hotdata.ConnectionsApi(api_client)
conn_api.load_managed_table(
    db.default_connection_id, "public", "partner_extract",
    hotdata.LoadManagedTableRequest(mode="replace", upload_id=up.upload_id),
)
```

### Step 6: Tear it down when you're done

Delete early, or just let `expires_at` clean it up for you.

**Claude**

```
I’m done with the scratch database — tear it down now instead of waiting for it to expire.
```

**CLI**

```bash
hotdata databases remove scratch
```

**Python SDK**

```python
import hotdata

db_api = hotdata.DatabasesApi(api_client)
db_api.delete_database("<database_id>")
```

## Who uses this

- Analysts prototyping joins before promoting logic to scheduled jobs.
- Agents that need real compute on temporary data, kept in a database that expires after the task.
- Platform folks who don't want half the company experimenting on one shared warehouse role.