createdb

Create a database owned by the current user

$ createdb [database_name]

$ createdb [[-O|--owner]] [username] [database_name] '[description]'

$ createdb [[-T|--template]] [template_name] [database_name]

createdb [OPTION]... [DBNAME [DESCRIPTION]]

-h, --host=HOSTNAME
    Database server host or socket directory

-p, --port=PORT
    Database server port (default: 5432)

-U, --username=NAME
    Database user name to connect as

-d, --dbname=DBNAME
    Connect to existing database (for connection)

-W, --password
    Force password prompt on connection

--no-password
    Never issue password prompt

-l, --locale=LOCALE
    Locale settings (LC_COLLATE, LC_CTYPE)

-E, --encoding=ENCODING
    Character set encoding for new database

--lc-collate=LC_COLLATE
    Collation order locale

--lc-ctype=LC_CTYPE
    Character classification locale

--template=TEMPLATE
    Template database to copy (default: template1)

-O, --owner=OWNER
    Owner of the new database

-T, --tablespace=TABLESPACE
    Tablespace for new database

-v, --verbose
    Enable verbose output

--version, -V
    Output version information

--help, -?
    Show help message

The createdb command is a wrapper around the PostgreSQL SQL CREATE DATABASE statement. It connects to a PostgreSQL server, typically as the current system user, and creates a new database named by the first non-option argument or the current username if omitted.

By default, the new database inherits settings from the template1 template database, including encoding, locale, and privileges. The connecting user becomes the owner unless overridden.

Supports full connection options for remote servers. Useful for scripting database setup in deployments or CI/CD pipelines. If the target database name exists, or if privileges are insufficient (requires superuser or CREATEDB role), it fails with an error.

Output includes confirmation like "createdb: database creation completed" in verbose mode.

Requires superuser privileges or CREATEDB role on the server. Cannot create databases in template0 or system catalogs. Connection database (default 'postgres') must exist. Fails if DBNAME already exists or exceeds namelength limit (NAMEDATALEN).

Honors PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE, PGPASSFILE, PGOPTIONS for connections.

0 on success, non-zero (1-3) on error: 1 general, 2 connection failure, 3 permissions.

Introduced in PostgreSQL 6.0 (1997) as a convenience wrapper for libpq clients. Evolved with PostgreSQL releases, adding locale/encoding options in 7.1 (2001) and tablespaces in 8.0 (2005). Maintained in current versions (16+).

dropdb(1), psql(1), pg_dump(1), initdb(1), postgres(1)