CLI Reference¶

Pure command lookup for DBWarden CLI.

Syntax¶

$ dbwarden [GLOBAL_OPTIONS] COMMAND [ARGS] [COMMAND_OPTIONS]

Global options¶

--debug/--debug-level set the logging severity and compose with the per-command --verbose/-v flag, which controls INFO-level verbosity. Use both (--debug plus -v) for DEBUG diagnostics with verbose INFO output. If both --debug and --debug-level are given, --debug-level wins.

Configuration¶

settings show¶

$ dbwarden settings show
$ dbwarden settings show primary
$ dbwarden settings show --all

database list¶

$ dbwarden database list

Migration authoring¶

make-migrations¶

$ dbwarden make-migrations "create users table" --database primary
$ dbwarden make-migrations --verbose --database primary
$ dbwarden --debug make-migrations --database primary
$ dbwarden --debug-level warning make-migrations --database primary
$ dbwarden make-migrations --plan --database primary
$ dbwarden make-migrations --rename users.username:email --database primary
$ dbwarden make-migrations --rename-table users:accounts --database primary
$ dbwarden make-migrations --safe-type-change --database primary

Options:

• --database/-d: Target database
• --plan: Print migration plan JSON without writing files
• --offline: Use model state file instead of live database (run export-models first)
• --verbose/-v: Verbose output
• --debug/--debug-level <LEVEL>: Global options (see Global options table). DEBUG shows every model file scanned during discovery.
• --rename: Repeatable. Declare a column rename in format table.old_name:new_name.
• --rename-table: Repeatable. Declare a table rename in format old_table:new_table.
• --safe-type-change: Multi-step safe type change strategy.
• --clickhouse-engine-recreate: Allow automatic ClickHouse table rebuild on engine change.
• --drop-preserved-clickhouse-table / --keep-preserved-clickhouse-table: Drop or keep the preserved old ClickHouse table after engine-recreate swap.
• --type/-t: Output prefix: versioned (default), ra/runs_always, or roc/runs_on_change.

See make-migrations for full documentation including rename detection, column-level changes, schema snapshots, and plan format.

new¶

$ dbwarden new "manual hotfix" --database primary
$ dbwarden new "backfill" --database primary --version 0042
$ dbwarden new "seed data" --database primary --type ra

Options: --database, --version, --type/-t

generate-models¶

$ dbwarden generate-models --output ./models/ --database primary
$ dbwarden generate-models --database primary --single-file
$ dbwarden generate-models --database primary --tables users,posts
$ dbwarden generate-models --database primary --exclude-tables logs,audit

Options: --output/-o (default models), --tables, --exclude-tables, --clickhouse-engines, --relationships, --dialect, --single-file, --base, --database/-d

export-models¶

$ dbwarden export-models --database primary
$ dbwarden export-models --database primary --output .dbwarden/model_state.json

Exports current model definitions to a JSON state file for offline migration diffs.

Important: The model state file is used for offline migration generation. It is auto-generated and committed to version control. If accidentally deleted, restore it from git or regenerate it by running dbwarden export-models --database <db> against a live database. Without it, offline commands like make-migrations --offline will not work, but online operations are unaffected.

Options: --output/-o (default .dbwarden/model_state.json), --database/-d

diff¶

$ dbwarden diff --database primary
$ dbwarden diff --database primary --out json
$ dbwarden diff --database primary --out sql
$ dbwarden diff --database primary --offline

Read-only model-vs-database comparison. No files are written.

Options: --database/-d, --out/-o (table, json, sql), --offline, --verbose/-v

check-impact¶

$ dbwarden check-impact 0042 --database primary
$ dbwarden check-impact 0042 --database primary --out json
$ dbwarden check-impact 0042 --database primary --scan-path app/
$ dbwarden check-impact path/to/primary__0042_add_bio.plan.json

Scans your codebase for references to schema elements affected by a migration.

Migration execution¶

migrate¶

$ dbwarden migrate --database primary
$ dbwarden migrate --all
$ dbwarden migrate --database primary --to-version 0010
$ dbwarden migrate --database primary --count 2
$ dbwarden migrate --database primary --with-backup
$ dbwarden migrate --database primary --baseline --to-version 0005

Options:

• --database, --all
• --to-version, --count
• --baseline
• --with-backup, --backup-dir
• --dry-run (show what would be applied without executing)
• --sandbox (apply in a temporary sandbox database)
• --apply-seeds (apply pending seeds after migrations, overrides config)
• --verbose

rollback¶

$ dbwarden rollback --database primary
$ dbwarden rollback --database primary --count 2
$ dbwarden rollback --database primary --to-version 0007

Options: --database, --count, --to-version, --verbose

downgrade¶

$ dbwarden downgrade --to 0005 --database primary

Options: --to (required), --database, --verbose

make-rollback¶

$ dbwarden make-rollback migrations/primary__0005_add_table.sql

Generates a .rollback.sql file for the given migration file.

snapshot¶

$ dbwarden snapshot users --database primary

Outputs the DDL schema of the specified table.

Seed management¶

seed create¶

$ dbwarden seed create "seed initial data" --database primary
$ dbwarden seed create "populate lookup tables" --database primary --type python

Options: --database, --type (sql or python, default sql), --verbose

seed apply¶

$ dbwarden seed apply --database primary
$ dbwarden seed apply --database primary --version 0003
$ dbwarden seed apply --database primary --dry-run
$ dbwarden seed apply --all

Options: --database, --all (-a), --version, --dry-run, --verbose

seed list¶

$ dbwarden seed list --database primary
$ dbwarden seed list --all
$ dbwarden seed list --prune

Options: --database, --all, --prune, --verbose

seed rollback¶

$ dbwarden seed rollback --database primary
$ dbwarden seed rollback --database primary --count 2
$ dbwarden seed rollback --database primary --to-version 0003
$ dbwarden seed rollback --all

Options: --database, --count, --to-version, --all, --verbose

seed export¶

$ dbwarden seed export --database primary
$ dbwarden seed export --all
$ dbwarden seed export --database clickhouse --output-dir ./seeds

Export code seeds to ROC SQL files for stateless production application.

Options: --database/-d, --all/-a, --output-dir/-o (default seeds/)

Inspection and diagnostics¶

status¶

$ dbwarden status --database primary
$ dbwarden status --all

history¶

$ dbwarden history --database primary

check-db¶

$ dbwarden check-db --database primary
$ dbwarden check-db --database primary --out json

Output formats: txt, json, yaml, sql

check¶

$ dbwarden check --database primary
$ dbwarden check --database primary --force
$ dbwarden check --database primary --out json

Output formats: txt, json

Locking¶

lock-status¶

$ dbwarden lock-status --database primary

unlock¶

$ dbwarden unlock --database primary

Plugin management¶

See the Plugins guide for the trust model and development docs.

plugin list¶

$ dbwarden plugin list
$ dbwarden plugin list --format json

Shows discovered plugins with tier, trust/load state, registered hooks, object handlers, and lock status.

Options: --format/-f (table or json, default table)

plugin info¶

$ dbwarden plugin info dbwarden-fastapi
$ dbwarden plugin info dbwarden-fastapi --format json

Shows entry point, tier, trust/load state, hooks, official repository, approved minimum version, and lockfile provenance. Exits 1 if the plugin is not found.

Options: --format/-f (table or json, default table)

plugin add¶

$ dbwarden plugin add dbwarden-fastapi
$ dbwarden plugin add dbwarden-fastapi --version 0.2.0 --uv
$ dbwarden plugin add dbwarden-example --dry-run

Installs a plugin. Official plugins are provenance-verified and fail closed if verification is unavailable; community plugins are installed but not trusted (run plugin trust next).

Options: --uv (use uv add instead of pip), --version (pin an exact version), --dry-run (print the plan without installing)

plugin remove¶

$ dbwarden plugin remove dbwarden-example
$ dbwarden plugin remove dbwarden-example --dry-run --uv

Uninstalls the distribution and removes its consent and lockfile entries.

Options: --uv (use uv remove instead of pip), --dry-run (print the plan without uninstalling)

plugin trust¶

$ dbwarden plugin trust dbwarden-example

Records consent for the installed version of a community plugin in .dbwarden/consent.toml. Consent is version-specific.

plugin untrust¶

$ dbwarden plugin untrust dbwarden-example

Revokes consent for a community plugin.

Utility¶

config¶

$ dbwarden config

version¶

$ dbwarden version

For worked command examples, see the Cookbook & Examples.