createdb: Usage, Options & Common CI Errors
createdb is a thin wrapper that creates a Postgres database without writing SQL.
createdb sets up the empty database a test suite or migration runs against. In CI it most often fails because the database already exists from a previous step or a reused container.
What it does
createdb is a command-line wrapper around the SQL CREATE DATABASE statement. It connects to the server and creates a new database, optionally setting owner, encoding, locale, or a template.
Common usage
PGPASSWORD=secret createdb -h localhost -U postgres app_test
createdb -h localhost -U postgres -O appuser app
createdb -h db -U postgres -E UTF8 -T template0 app
createdb -h localhost -U postgres app || true # ignore if it existsOptions
| Flag | What it does |
|---|---|
| -h <host> / -p <port> | Server host / port |
| -U <user> | Connect as this role |
| -O <owner> | Database owner |
| -E <encoding> | Character encoding (e.g. UTF8) |
| -T <template> | Template database (template0/template1) |
Common errors in CI
createdb: error: database creation failed: ERROR: database "app" already exists - guard with || true, or DROP it first, when a container is reused across jobs. "ERROR: permission denied to create database" means the role lacks CREATEDB - connect as a superuser like postgres. "ERROR: source database "template1" is being accessed by other users" appears when something is connected to the template; -T template0 avoids it.