initdb

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

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

initdb [OPTION]... [DATADIR]

-A method, --auth=method
    Set default authentication method for local connections (e.g., trust, peer, md5).

--auth-host=method
    Authentication method for TCP/IP connections.

--auth-local=method
    Authentication method for local socket connections.

--auth-peer=user
    Peer authentication user mapping.

-D directory, --pgdata=directory
    Set data directory location for new cluster.

--allow-group-access
    Allow group access to data directory (world-readable configs).

-d, --debug
    Print debugging output.

--data-checksums
    Enable data page checksums.

-E encoding, --encoding=encoding
    Set default encoding (e.g., UTF8).

-L directory
    Directory for input files.

--locale=locale
    Set default locale (or use --lc-*)

--lc-collate=locale
    Collation locale.

--lc-ctype=locale
    Character classification locale.

--lc-messages=locale
    Message language locale.

--lc-monetary=locale
    Monetary formatting locale.

--lc-numeric=locale
    Number formatting locale.

--lc-time=locale
    Time formatting locale.

--locale-provider={libc|icu}
    Locale provider (default libc).

--log-file=filename
    Log output to file.

--no-locale
    Equivalent to C locale settings.

--pwprompt, -W
    Prompt for superuser password.

--pwfile=filename
    Read superuser password from file.

-s, --show
    Show internal settings (deprecated).

--sync-only
    Sync but do not start WAL logging.

--text-search-config=config
    Default text search configuration.

-U username, --username=username
    Superuser name (default postgres).

--waldir=directory
    WAL directory location.

--xlogdir=directory
    Deprecated alias for --waldir.

initdb creates a new PostgreSQL database cluster, setting up the directory structure, configuration files, and initial databases required for a PostgreSQL server instance.

A database cluster consists of a shared directory containing databases, WAL logs, configuration files like postgresql.conf and pg_hba.conf, and system catalogs. It initializes template databases (template0, template1), the default postgres database, and a superuser account.

Run it before starting the server with pg_ctl or systemd. Specify the data directory (PGDATA) via -D or --pgdata; defaults to environment variables. Customize encoding, locale, authentication, and checksums via options. Requires write access to PGDATA; typically run by the postgres user.

Process includes syncing data to disk unless disabled. Generates random cluster identifier. Post-init, adjust configs and start server. Essential for new PostgreSQL installations; clusters cannot be safely reinitialized if containing data.

Data directory must not exist or be empty; backup first. Avoid running as root—use dedicated postgres user. Fails if PGDATA locked by running server. Custom locales require system support. Checksums add CPU overhead but detect corruption.

initdb -D /var/lib/pgsql/15/data --auth-local=peer --encoding=UTF8
Initializes cluster in specified dir with peer auth and UTF8.

Respects PGDATA, PGHOST, etc. See postgres(1).

Introduced in PostgreSQL 6.0 (1997) as replacement for ad-hoc init scripts. Gained data checksums in 9.3 (2013), ICU locale support in 10 (2017), WAL directory separation in 12 (2019). Evolved for security, performance, and internationalization.

pg_ctl(1), postgres(1), createdb(1), pg_dumpall(1), pg_hba.conf(5)