bunny db - bunny.net Documentation

bunny db provides full lifecycle management for Bunny Database: creating databases, linking them to local projects, running SQL interactively, applying schema migrations, generating auth tokens, and viewing tables in a browser.

Database resolution

Most db commands accept an optional <database-id> positional argument. When omitted, the CLI resolves the target in this order:

Explicit <database-id> argument
.bunny/database.json manifest written by bunny db link
BUNNY_DATABASE_URL in a .env file (walked up from the current directory) matched against your database list
Interactive selection prompt

For bunny db shell, the CLI also reads BUNNY_DATABASE_AUTH_TOKEN from .env to skip token generation. Both variables can be written automatically by bunny db create or bunny db quickstart.

`bunny db create`

Create a new database. Interactively prompts for name and region selection (automatic, single region, or manual) when flags are omitted. After creation, prompts to link the directory, generate an auth token, and save credentials to .env.

# Interactive: prompts for name and region mode
bunny db create

# Single region
bunny db create --name mydb --primary FR

# Multi-region with replicas
bunny db create --name mydb --primary FR,DE --replicas UK,NY

# Fully non-interactive (CI / scripts)
bunny db create --name mydb --primary FR --link --token --save-env --output json

Flag	Description
`--name`	Database name
`--primary`	Comma-separated primary region IDs (e.g. `FR` or `FR,DE`)
`--replicas`	Comma-separated replica region IDs (e.g. `UK,NY`)
`--storage-region`	Override the auto-detected storage region
`--link`	Link the current directory to the new database (skips prompt). Use `--no-link` to skip.
`--token`	Generate a full-access auth token (skips prompt). Use `--no-token` to skip.
`--save-env`	Save `BUNNY_DATABASE_URL` and `BUNNY_DATABASE_AUTH_TOKEN` to `.env`. Requires `--token`.

In --output json mode, prompts are suppressed entirely. Flags are the only way to opt in to linking, token creation, and .env writes. The JSON output gains linked, token, and saved_to_env fields reflecting what happened.

`bunny db list`

List all databases. Shows ID, name, status, primary region, and size.

bunny db list
bunny db list --output json

`bunny db show`

Show details for a single database.

bunny db show <database-id>
bunny db show
bunny db show --output json

`bunny db link`

Link the current directory to a database. Writes { id, name } to .bunny/database.json so subsequent db commands resolve the target without BUNNY_DATABASE_URL in .env. With no argument, lists all databases for interactive selection.

# Interactive selection
bunny db link

# Direct link by ID
bunny db link <database-id>

bunny db create offers to link the new database, and bunny db delete automatically removes a stale link when it points at the deleted database.

`bunny db delete`

Permanently delete a database. Requires double confirmation (or --force to skip).

bunny db delete <database-id>
bunny db delete --force

Flag	Description
`--force`	Skip confirmation prompts

`bunny db regions`

Manage primary and replica regions for a database.

`bunny db regions list`

bunny db regions list
bunny db regions list <database-id>

`bunny db regions add`

bunny db regions add --primary FR,DE
bunny db regions add --replicas UK,NY
bunny db regions add --primary FR --replicas UK

Flag	Description
`--primary`	Comma-separated primary region IDs to add
`--replicas`	Comma-separated replica region IDs to add

`bunny db regions remove`

bunny db regions remove --primary FR
bunny db regions remove --replicas UK,NY

Flag	Description
`--primary`	Comma-separated primary region IDs to remove
`--replicas`	Comma-separated replica region IDs to remove

`bunny db regions update`

Interactively update region configuration. Shows all available regions with current ones pre-selected. Toggle on/off and confirm.

bunny db regions update
bunny db regions update <database-id>

`bunny db usage`

Show usage statistics for a database.

bunny db usage <database-id>
bunny db usage --period 7d
bunny db usage --output json

`bunny db quickstart`

Generate a quickstart guide for connecting to a database from your preferred language.

bunny db quickstart
bunny db quickstart <database-id> --lang bun

`bunny db shell`

Open an interactive SQL shell for a database. Supports multiple output modes, sensitive column masking, persistent history, and dot-commands for quick introspection.

When no --token is supplied and BUNNY_DATABASE_AUTH_TOKEN is not set, the shell session is active for 30 minutes. Re-run the command to reconnect, or pass --token / set BUNNY_DATABASE_AUTH_TOKEN to use your own credentials.

# Interactive shell (auto-detects database from .env)
bunny db shell

# Specify a database ID
bunny db shell <database-id>

# Execute a query and exit
bunny db shell "SELECT * FROM users"
bunny db shell <database-id> "SELECT * FROM users"
bunny db shell --execute "SELECT COUNT(*) FROM posts"

# Output modes
bunny db shell -m json -e "SELECT * FROM users"
bunny db shell -m csv -e "SELECT * FROM users"
bunny db shell -m markdown -e "SELECT * FROM users"

# Execute a SQL file
bunny db shell -e seed.sql
bunny db shell seed.sql

# Show sensitive columns unmasked
bunny db shell --unmask

# Direct connection (skip API lookup)
bunny db shell --url libsql://... --token ey...

Flag	Alias	Description
`--execute`	`-e`	Execute a SQL statement and exit
`--mode`	`-m`	Output mode: `default`, `table`, `json`, `csv`, `markdown`
`--unmask`		Show sensitive column values unmasked
`--url`		Database URL (skips API lookup)
`--token`		Auth token (skips token generation)

Dot-commands

Available in interactive mode:

Command	Description
`.tables`	List all tables
`.describe TABLE`	Show column details for a table
`.schema [TABLE]`	Show CREATE statements
`.indexes [TABLE]`	List indexes
`.fk TABLE`	Show foreign keys for a table
`.er`	Show entity-relationship overview
`.count TABLE`	Count rows in a table
`.size TABLE`	Show table stats (rows, columns, indexes)
`.truncate TABLE`	Delete all rows from a table
`.dump [TABLE]`	Dump schema and data as SQL
`.read FILE`	Execute SQL statements from a file
`.mode [MODE]`	Set output mode
`.timing`	Toggle query execution timing
`.mask`	Enable sensitive column masking
`.unmask`	Disable sensitive column masking
`.clear-history`	Clear command history
`.help`	Show available commands
`.quit` / `.exit`	Exit the shell

Sensitive column masking

Columns matching patterns like password, secret, api_key, auth_token, ssn, etc. are masked by default (********). Email columns are partially masked (a••••e@example.com). Use .unmask or the --unmask flag to reveal values.

`bunny db studio`

Open a read-only table viewer in your browser. Spins up a local server, generates a short-lived auth token if needed, and opens the studio UI.

# Auto-detect database (link, .env, or interactive)
bunny db studio

# Specific database
bunny db studio <database-id>

# Custom port
bunny db studio --port 3000

# Don't auto-open the browser
bunny db studio --no-open

# Use explicit credentials (skips API lookup)
bunny db studio --url libsql://... --token ey...

Flag	Description
`--port`	Port for the local studio server (default 4488)
`--url`	Database URL (skips API lookup)
`--token`	Auth token (skips token generation)
`--no-open`	Don’t automatically open the browser

`bunny db migrations`

Create and apply versioned SQL migrations. Migration files live on disk, run in filename order, and carry a tracking row in the database, so the CLI applies each file exactly once. See Migrations for the full workflow, including ORM output and running migrations in CI.

`bunny db migrations create`

Create an empty, numbered migration file. The filename is the migration’s identity, so the numeric prefix decides the order apply runs them in.

# Creates migrations/0001_add_users_table.sql
bunny db migrations create add_users_table

# Names are slugified, so quoting works
bunny db migrations create "add users table"

# Custom directory
bunny db migrations create add_index --dir db/migrations

Flag	Description
`--dir`	Migrations directory (default: `migrations`)

Aliased as bunny db migrations new. Creation never auto-detects an ORM output directory: writing a hand-authored file there would bypass the ORM’s own journal. The new file holds only a comment, so add SQL before applying it. apply rejects a migration with no statements.

`bunny db migrations list`

Show which migrations have been applied. Read-only: it never creates the tracking table.

bunny db migrations list
bunny db migrations list <database-id>
bunny db migrations list --output json

Flag	Description
`--dir`	Migrations directory (default: `migrations`)
`--pattern`	Migration glob relative to `--dir` (default `*.sql`)
`--url`	Database URL (skips API lookup)
`--token`	Auth token (skips token generation)

Aliased as ls and status. Each migration is reported in one of five states:

State	Meaning
`Applied`	On disk and recorded, with matching checksums
`Pending`	On disk, with no record of a run
`Modified`	Recorded, and the file has changed since it ran
`Missing`	Recorded, and the file has gone from disk
`Out of order`	Pending, and sorts before a migration that already ran

`bunny db migrations apply`

Apply every pending migration, in filename order. Each file runs as one atomic batch together with its tracking row, so a migration either lands and is recorded or neither happens. Foreign keys are deferred for the batch, so table rebuilds work. The run stops at the first failure and leaves the remaining migrations pending.

# Apply all pending migrations
bunny db migrations apply

# Show what would run, without writing
bunny db migrations apply --dry-run

# Apply drizzle-kit output
bunny db migrations apply --dir drizzle

# Nested ORM layouts
bunny db migrations apply --dir drizzle --pattern "*/migration.sql"

Flag	Description
`--dir`	Migrations directory (default: `migrations`)
`--pattern`	Migration glob relative to `--dir` (default `*.sql`)
`--url`	Database URL (skips API lookup)
`--token`	Auth token (skips token generation)
`--dry-run`	List the migrations that would run, without applying them
`-f, --force`	Skip confirmation prompts
`--allow-drift`	Apply against a modified, missing, or out-of-order history

A dry run and a declined confirmation both leave the database untouched, including the tracking table. Against a drifted history, apply refuses and applies nothing until you pass --allow-drift. The CLI only prompts for confirmation when stdin is an interactive terminal, so CI runs don’t hang. The CLI records applied migrations in a __bunny_migrations table. The __ prefix keeps it out of studio and REST introspection. When migrations/ doesn’t exist and you pass no --dir, the CLI falls back to drizzle/ if it’s present, so drizzle-kit generate output works with no configuration. Every migration file is parsed before the first database write, so a malformed later file cannot leave a run half-complete.

`bunny db tokens`

Generate and invalidate database auth tokens.

`bunny db tokens create`

Generate an auth token for a database. The database ID can be provided as a positional argument or auto-detected from BUNNY_DATABASE_URL in a .env file.

# Provide database ID explicitly
bunny db tokens create <database-id>

# Auto-detect from .env BUNNY_DATABASE_URL
bunny db tokens create

# Read-only token
bunny db tokens create --read-only

# Token with expiry (duration shorthand or RFC 3339)
bunny db tokens create --expiry 30d
bunny db tokens create --expiry 2026-12-31T23:59:59Z

Flag	Description
`--read-only`	Generate a read-only token (default: full access)
`-e, --expiry`	Token expiry. Duration (`30d`, `12h`, `1w`, `1m`, `1y`) or RFC 3339 date

`bunny db tokens invalidate`

Invalidate all auth tokens for a database. Prompts for confirmation unless --force is passed.

bunny db tokens invalidate <database-id>
bunny db tokens invalidate --force

Flag	Description
`--force`	Skip confirmation prompts

​Database resolution

​bunny db create

​bunny db list

​bunny db show

​bunny db link

​bunny db delete

​bunny db regions

​bunny db regions list

​bunny db regions add

​bunny db regions remove

​bunny db regions update

​bunny db usage

​bunny db quickstart

​bunny db shell

​Dot-commands

​Sensitive column masking

​bunny db studio

​bunny db migrations

​bunny db migrations create

​bunny db migrations list

​bunny db migrations apply

​bunny db tokens

​bunny db tokens create

​bunny db tokens invalidate

Database resolution

`bunny db create`

`bunny db list`

`bunny db show`

`bunny db link`

`bunny db delete`

`bunny db regions`

`bunny db regions list`

`bunny db regions add`

`bunny db regions remove`

`bunny db regions update`

`bunny db usage`

`bunny db quickstart`

`bunny db shell`

Dot-commands

Sensitive column masking

`bunny db studio`

`bunny db migrations`

`bunny db migrations create`

`bunny db migrations list`

`bunny db migrations apply`

`bunny db tokens`

`bunny db tokens create`

`bunny db tokens invalidate`