CLI usage

dbsp reaches one managed DDL executor from two commands. The reviewed path is plan a change, then apply it: a no-argument apply creates, persists, and presents a fresh managed run, and an apply <run-id> executes exactly that replayable recorded run. dbsp migrate converges a schema file without review and admits only additions and declared adoptions. There is no migration-file apply or rollback workflow.

Managed workflow

Command	Purpose
dbsp plan	Compare declared and live state, prove a managed plan, and record it.
dbsp apply [run-id]	Present and execute one replayable managed plan; without an id it persists before presenting.
dbsp inspect [address]	Read the ledger and live state without repairing it.
dbsp reconcile <run-id>	Classify a previously recorded run against live state.
dbsp release <address>	Release managed authority when its safety checks permit it.
dbsp preflight --reinitialize	Check and explicitly reinitialize a managed ledger when allowed.
dbsp migrate <schema-file>	Converge the schema to the file without review, through convergePg.

dbsp plan ./schema.ts --db "$DATABASE_URL" --schema "$DBSP_SCHEMA"
# Run the recorded id and digest printed by the preceding command.
dbsp apply "$RUN_ID" --db "$DATABASE_URL" --plan-digest "$PLAN_DIGEST" --accept operation-pack-semantics --accept external-ddl-exclusion
dbsp inspect table:users --db "$DATABASE_URL" --schema "$DBSP_SCHEMA" --format json

--dry-run on no-argument apply does not persist a run. Keep the run ID and digest printed by plan or apply: a recorded apply <run-id> is available only for replayable runs. A declined removal is not replayable; re-plan it when you are ready to proceed. --yes accepts the presentation step.

For plan, no-argument apply, and preflight --reinitialize, dbsp creates one PostgreSQL physical model from the loaded schema file, its dbCasing, and the target schema. The resulting physical names are used for declarations and transition planning; commands do not remap declared names themselves.

Startup convergence

dbsp migrate ./schema.ts --db "$DATABASE_URL" --schema "$DBSP_SCHEMA" --format json

dbsp migrate runs convergePg once: it creates what the schema file adds, adopts the tables and sequences it marks adopt: true, and refuses any other change before sending DDL. dbsp plan and dbsp apply adopt tables only; they refuse a sequence marked adopt: true. It asks for no confirmation and has no dry run; review a change with dbsp plan instead. The schema needs its ledger first, from dbsp preflight --reinitialize. Name each index you manage yourself with --external-index <model-table>:<index>: the table as the model names it, before dbCasing maps it, then the index by its exact PostgreSQL name; the table part cannot contain :. Every result and refusal is a named outcome with its own exit code, listed by dbsp migrate --help; no-drift and applied exit 0. A command-line syntax error, such as a missing --db, exits 1 like every dbsp command.

Other local tools

dbsp generate ddl renders SQL for review or caller-owned execution. It is an explicitly unmanaged API: it does not connect to a database, claim ledger authority, or apply SQL. dbsp repl, introspect, and verify remain local exploration and validation tools.

Output

Commands that support JSON emit one JSON document to stdout. Human diagnostics escape control and terminal-control sequences in database-controlled names; SQL text, credentials, and declarations are not logged by default.

Published internal adapter export

@dbsp/adapter-pgsql/internal is a published subpath used by DBSP's managed facade. It is unsupported for external integrations; in-process use is trusted by declaration and the subpath is not a security boundary. Use the public adapter APIs for supported integrations.