createdb

Create a database owned by the current user

$ createdb [database_name]

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

$ createdb --template [template_name] [database_name]

createdb [connection-options] [option...] [dbname [template]]

connection-options:
  -h host, --host=host
  -p port, --port=port
  -U username, --username=username
  -W, --password

option...:
  -D tablespace, --tablespace=tablespace
  -E encoding, --encoding=encoding
  -e, --echo
  -l locale, --locale=locale
  -O owner, --owner=owner
  -T template, --template=template
  -V, --version
  -?, --help

dbname: The name of the new database to create.
template: The name of the template database to copy (default is template1).

-D tablespace, --tablespace=tablespace
    Specifies the default tablespace for the new database.

-E encoding, --encoding=encoding
    Specifies the character set encoding to use for the new database.

-e, --echo
    Echoes the commands that createdb generates and sends to the server. Useful for debugging.

-l locale, --locale=locale
    Specifies the locale settings (LC_CTYPE and LC_COLLATE) to be used in the new database.

-O owner, --owner=owner
    Specifies the role name of the user who will own the new database.

-T template, --template=template
    Specifies the name of the template database to copy. Defaults to template1.

-V, --version
    Prints the createdb version and exits.

-?, --help
    Shows help about createdb command line arguments and exits.

-h host, --host=host
    Specifies the host name of the machine on which the PostgreSQL server is running. If empty, the local Unix domain socket is used.

-p port, --port=port
    Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections.

-U username, --username=username
    User name to connect as (defaults to current operating system user).

-W, --password
    Forces createdb to prompt for a password before connecting to the database.

createdb is a utility for creating new PostgreSQL databases. It is a wrapper around the SQL command CREATE DATABASE, which is executed on a PostgreSQL server. This command simplifies the process of database creation by abstracting away the need to manually connect to psql and execute the CREATE DATABASE statement. It requires a running PostgreSQL server and appropriate permissions for the connecting user to create databases.

Essentially, createdb connects to a specified PostgreSQL instance (or the default one) and sends the instruction to create a database with the given name and options. If a template database is specified, the new database will be a copy of that template; otherwise, it will copy from the default template1.

The PostgreSQL server must be running and accessible for createdb to connect successfully.
The user running createdb must have the CREATEDB privilege in PostgreSQL to create new databases.
Encoding and locale settings are permanent for a database and cannot be changed after creation without dropping and recreating the database.
When creating a database from a template, any objects or data present in the template will be copied to the new database. Be mindful if template1 (the default) has been modified.

Avoid hardcoding passwords directly in shell scripts. Instead, use environment variables like PGPASSWORD, or preferably, a .pgpass file for secure password storage. Ensure the PostgreSQL user specified with -U has only the necessary privileges (e.g., CREATEDB) and not excessive administrative rights.

createdb is commonly used for automating database creation as part of application deployment pipelines, setting up development or test environments quickly, or creating databases with specific character sets and locale settings for internationalization requirements.

createdb has been an integral part of the PostgreSQL client utilities since its early versions, providing a straightforward command-line interface to the CREATE DATABASE SQL command. Its design reflects the common need for scripting database setup and management tasks without directly interacting with psql. Its functionality has remained largely consistent, evolving primarily with new features in PostgreSQL databases themselves, such as support for tablespaces, different encoding options, and improved connection parameters.

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