initdb

Create a database at /usr/local/var/postgres

$ initdb [[-D|--pgdata]] /usr/local/var/postgres

initdb [option...] [--pgdata | -D] directory

-D directory, --pgdata=directory
    This option specifies the directory where the database cluster will be stored. This is a mandatory option.

-E encoding, --encoding=encoding
    Sets the default encoding for new databases. For example, UTF8. The default is derived from the locale.

-U username, --username=username
    Sets the database superuser's name for the new cluster. This user will own all system catalogs and initial databases. The default is the name of the operating system user running initdb.

-W, --pwprompt
    Causes initdb to prompt for a password for the database superuser. If you don't set a password, authentication will be trust-based for local connections initially.

-A authmethod, --auth-local=authmethod, --auth-host=authmethod
    Sets the default authentication method for local (--auth-local) and TCP/IP (--auth-host) connections in pg_hba.conf. Common methods include trust, ident, md5, scram-sha-256. Default is ident for local connections and scram-sha-256 for host connections if the cluster is initialized with a superuser password, otherwise trust.

-X waldir, --waldir=wal_directory
    Specifies the directory where the transaction log (WAL) will be stored. This can be used to place the WAL on a different disk for performance or reliability.

-k, --data-checksums
    Enables data checksums for all data pages. Checksums help detect disk and file system corruption, but incur a small performance overhead. Once enabled, they cannot be turned off without reinitializing the cluster.

--no-locale
    Equivalent to setting the locale to C (or POSIX). This is a faster option than defining a specific locale as it avoids locale-dependent sorting overhead. Useful for performance-critical applications or when locale awareness is not needed.

--locale=locale
    Sets the default locale for the database cluster. This affects sorting order, character classification, and formatting of dates and numbers. All other locale settings (like lc_collate, lc_ctype) are set to this value unless overridden by specific options.

--lc-collate=locale, --lc-ctype=locale, etc.
    These options allow setting specific locale categories independently (e.g., for collation, character types, messages, monetary, numeric, time). Overrides --locale for that specific category.

--pwfile=filename
    Reads the database superuser's password from a file. This is useful for scripting initdb without exposing the password on the command line.

-L directory, --localedir=directory
    Specifies the directory where locale information can be found. This is typically only useful if you're using a custom locale setup.

-N, --noclean
    By default, when initdb fails, it removes any files it created. This option prevents that cleanup, which can be useful for debugging.

--version
    Prints the initdb version and exits.

--help
    Shows help about initdb command line arguments, and exits.

initdb is a PostgreSQL utility used to create a new PostgreSQL database cluster. A database cluster is a collection of databases managed by a single server instance. Running initdb creates the directory structure where all the data will live, generates the shared catalog tables (template databases), and creates the template0 and template1 databases, along with the default 'postgres' database. It also sets up default configuration files like postgresql.conf and pg_hba.conf, which control the server's behavior and client authentication.

This command is the first essential step before you can start a PostgreSQL server for the first time in a new data directory. It does not start the PostgreSQL server; it merely prepares the directory for the server to be started by commands like pg_ctl or postgres itself. It's crucial to ensure the data directory specified is either empty or does not exist, as initdb will populate it with the necessary files.

initdb must be run by the operating system user that will later own the PostgreSQL server process. The target data directory must be empty or non-existent; initdb will refuse to initialize a directory that already contains data. Ensure sufficient disk space is available for the initial setup. Data checksums, once enabled with -k, cannot be disabled without reinitializing the cluster.

When initdb is run, it creates a database superuser. By default, this user has the same name as the operating system user who invoked initdb. This superuser is critical for initial database administration tasks, including creating new databases and users, and modifying system settings. It's recommended to set a strong password for this user using the -W or --pwfile options.

initdb creates several crucial configuration files in the data directory, most notably postgresql.conf and pg_hba.conf. postgresql.conf controls server parameters like memory usage, logging, and connections. pg_hba.conf (Host-Based Authentication) controls client authentication rules, determining who can connect to the database and how they must authenticate. These files are essential for customizing and securing your PostgreSQL installation and should be reviewed after initialization.

initdb has been a fundamental utility in PostgreSQL since its earliest versions, serving as the initial setup tool for any new database cluster. Its core functionality has remained consistent: to prepare the data directory for a running PostgreSQL server. Over time, new options have been added to support features like data checksums, improved authentication methods, and more flexible locale management, reflecting the evolving needs and capabilities of the PostgreSQL database system.

pg_ctl(1), postgres(1), pg_hba.conf(5), postgresql.conf(5)