> ## Documentation Index
> Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Database work

> Ephemeral Postgres per agent session. Local Supabase for testing generated RLS policies, migrations, and RESTful queries against a fresh DB.

Customers ask AI agents to write and run SQL. If you're running that
SQL against a shared test DB, you're one `DROP TABLE` hallucination
away from ruining everyone's afternoon. Podflare gives each session
its own fresh Postgres (or Supabase stack) that evaporates when the
sandbox ends.

## Ephemeral Postgres per session

Install Postgres inside the sandbox, start it, connect as a user
the agent can't escalate out of:

```python theme={null}
from podflare import Sandbox

sbx = Sandbox(template="python-datasci")

# Install + start Postgres
sbx.run_code("""
import subprocess
subprocess.run(['apt-get', 'install', '-y', '-qq', 'postgresql'], check=True)
subprocess.run(['service', 'postgresql', 'start'], check=True)
subprocess.run(
    ['sudo', '-u', 'postgres', 'psql', '-c',
     "CREATE USER agent SUPERUSER PASSWORD 'dev';"],
    check=True,
)
""")

# Agent-generated schema + test
r = sbx.run_code("""
import psycopg
conn = psycopg.connect('postgresql://agent:dev@localhost/postgres')
cur = conn.cursor()
cur.execute('''
CREATE TABLE IF NOT EXISTS users (id serial primary key, email text);
INSERT INTO users(email) VALUES ('alice@ex.com'), ('bob@ex.com');
''')
conn.commit()

cur.execute("SELECT count(*), max(id) FROM users")
print(cur.fetchone())
""")

print(r.stdout)
sbx.close()
```

### What this unlocks

* **"Test my migration" agents.** Customer pastes a migration SQL,
  agent runs it against a fresh DB, returns whether it applies,
  what changed, and any lint warnings.
* **Generated-query validators.** Agent writes SQL, agent runs it
  against a schema-only copy, catches syntax errors before showing
  the user.
* **Demo environments.** Each trial user gets their own Postgres;
  teardown is automatic at sandbox end.

## Local Supabase stack

For AI apps being built on Supabase, you want the full stack —
Postgres + PostgREST + GoTrue + Storage — not just raw Postgres.
Supabase's CLI starts everything with one command:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

# Supabase CLI
curl -sSL https://github.com/supabase/cli/releases/latest/download/supabase_linux_amd64.tar.gz \
  | tar xz -C /usr/local/bin

# The podflare-datasci template already has Docker available
supabase init --yes
supabase start

# Run the agent's generated SQL against the fresh DB
psql "postgresql://postgres:postgres@localhost:54322/postgres" \
     -f /tmp/agent-generated-migrations.sql

# Test PostgREST against the applied schema
curl -sS "http://localhost:54321/rest/v1/users?select=*" \
  -H "apikey: anon-key" \
  | head -100

supabase stop
```

Wire this into your agent loop the same way:

```python theme={null}
from podflare import Sandbox

sbx = Sandbox(template="python-datasci", idle_timeout_seconds=1800)

# Start Supabase in the background (takes ~20s)
sbx.run_code(open("scripts/start-supabase.sh").read(), language="bash")

# Now the agent can issue REST queries + SQL migrations
# against a fully-local Supabase project
```

## Per-session isolation matters

All of the above run **only** in the lifetime of one sandbox. When
the sandbox dies — explicit `destroy`, idle timeout, max lifetime —
the database, its rollbacks, its generated data all go with it.
No orphan DBs. No "whose user table is this?" cleanup scripts.

## Pitfalls

* **Start-up cost is real.** Postgres cold-start: \~2–4 s. Supabase:
  \~15–25 s. Run the install in the sandbox's first turn, keep the
  sandbox alive across the agent's session.
* **Free tier caps at 1 GB RAM** — enough for Postgres + a small
  Supabase; not enough for big data loads. Upgrade to Pro (4 GB)
  for real workloads.
* **If you need the DB after the session ends**, dump with
  `pg_dump` at the end and download the file via the sandbox
  file API. Otherwise it's gone.