On this page
Reference for the pgdesign testdb command group — init, setup, teardown, and gc subcommands for ephemeral test databases with optional partman CI support.
#pgdesign testdb
Manage ephemeral test databases for schema testing
#testdb gc
Drop orphaned test databases that were not properly torn down after test runs. Scans the PostgreSQL server for databases matching the pgdesign test naming pattern and removes those older than the specified duration. Useful for cleaning up after interrupted or failed test runs in CI and local development.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server | ||
--older-than | str | Drop databases older than this duration (e.g., 2h, 30m) |
#testdb init
Generate test database wrapper code for consumer projects that need to run integration tests against a pgdesign-managed schema. Produces language-specific helper modules with setup and teardown functions that create ephemeral databases, apply DDL, and clean up automatically after each test run.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--language | str | Target programming language(s) for wrapper generation | |||
--output | str | Name of the SQL output section (for disambiguation) | |||
--force-overwrite | bool | Overwrite existing wrapper files without prompting | |||
--ci | str | CI provider for workflow generation (e.g., github-actions) | |||
--partman | bool | Include pg_partman installation step in CI workflow |
#testdb setup
Create an ephemeral test database on the PostgreSQL server and apply the specified DDL schema to it. The database is created with a unique name containing a timestamp and random suffix to allow parallel test execution. Returns the connection URL for the new database.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server | ||
--ddl | str | Path to the SQL DDL file to apply to the test database |
#testdb teardown
Drop an ephemeral test database that was previously created by testdb setup. Terminates any remaining connections to the database before dropping it. Should be called in test cleanup to prevent orphaned databases from accumulating on the PostgreSQL server over time.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--db | str | PGDESIGN_DB | PostgreSQL connection URL for the target database server |