dropdb: Usage, Options & Common CI Errors
dropdb removes a Postgres database without an interactive SQL session.
dropdb resets state between CI runs. Its two recurring failures are dropping a database that does not exist and dropping one that still has open connections.
What it does
dropdb is a command-line wrapper around DROP DATABASE. It permanently removes a database and all of its data, which makes it useful for clean-slate test setup and teardown.
Common usage
PGPASSWORD=secret dropdb -h localhost -U postgres app_test
dropdb -h localhost -U postgres --if-exists app_test
dropdb -h db -U postgres -f app # force: terminate connections first
dropdb -h localhost -U postgres --if-exists app && createdb ... appOptions
| Flag | What it does |
|---|---|
| -h <host> / -p <port> | Server host / port |
| -U <user> | Connect as this role |
| --if-exists | Do not error if the database is missing |
| -f / --force | Terminate existing connections first (PG13+) |
| -i / --interactive | Prompt before dropping (avoid in CI) |
Common errors in CI
dropdb: error: database removal failed: ERROR: database "app" does not exist - use --if-exists in idempotent teardown. "ERROR: database "app" is being accessed by other users" - an open connection (often a leftover pool) blocks the drop; pass -f (PostgreSQL 13+) to terminate sessions, or you cannot drop the database you are currently connected to, so connect to postgres instead.