initdb & Data Directory

initdb creates a new PostgreSQL cluster on disk. The data directory (PGDATA) holds all databases, WAL, and configuration for that single instance.

Recipe

sudo -u postgres mkdir -p /var/lib/postgresql/18/main
sudo -u postgres /usr/lib/postgresql/18/bin/initdb \
  -D /var/lib/postgresql/18/main \
  --encoding=UTF8 \
  --locale=C.UTF-8 \
  --data-checksums

When to reach for this: First cluster on a host, restoring to a blank data directory, or building a standby before pg_basebackup.

Working Example

# Create dedicated mount points (production pattern)
sudo mkdir -p /data/pgdata /data/pgwal
sudo chown postgres:postgres /data/pgdata /data/pgwal
sudo chmod 700 /data/pgdata /data/pgwal
 
sudo -u postgres initdb \
  -D /data/pgdata \
  --waldir=/data/pgwal \
  --encoding=UTF8 \
  --locale=en_US.UTF-8 \
  --data-checksums
 
# Confirm layout
sudo -u postgres ls -la /data/pgdata
sudo -u postgres ls -la /data/pgdata/base

What this demonstrates:

• Separate PGDATA and WAL on different volumes for IO isolation
• 700 permissions on data dirs (owner-only access)
• --data-checksums enables page checksum verification at read time
• base/ subdirectory appears after init - one subdir per database OID

Deep Dive

PGDATA Layout (Key Paths)

Permissions Model

# Correct ownership
ls -ld /data/pgdata
# drwx------ postgres postgres
 
# Wrong: group or world readable
chmod 750 /data/pgdata   # avoid - leaks catalog metadata risk

• Only the postgres OS user should read/write PGDATA.
• Backup tools run as postgres or use filesystem snapshots with correct UID.
• Never run initdb as root - the server refuses to start on root-owned data.

Locale and Encoding

-- Set at init time; changing later requires re-init
SHOW server_encoding;  -- UTF8
SHOW lc_collate;         -- en_US.UTF-8
SHOW lc_ctype;

• Prefer UTF8 encoding for all new clusters.
• C or C.UTF-8 collation gives predictable sort order; locale-specific collation affects index order.
• ICU locales (--locale-provider=icu) are available in PostgreSQL 15+.

WAL Directory Separation

# postgresql.conf (if not set at initdb)
# wal_directory is set at init via --waldir; relocate carefully with pg_resetwal only in disaster recovery

• WAL is append-heavy; data files are random IO - separate SSD/NVMe pools when IO-bound.
• Document both paths in your inventory - restores must recreate the same layout.

Gotchas

• Re-running initdb on existing PGDATA - initdb fails if the directory is non-empty. Fix: Use a fresh empty directory or pg_basebackup for replicas.
• Wrong ownership after restore - chown from backup tar as root leaves root-owned files. Fix: chown -R postgres:postgres $PGDATA before start.
• Missing data checksums - Clusters created without --data-checksums cannot enable them later without re-init. Fix: Enable at init; plan checksum-aware monitoring.
• Locale mismatch across replicas - Standby init with different lc_collate breaks index ordering assumptions. Fix: Match initdb flags on all nodes in a topology.
• Full disk on PGDATA - initdb needs scratch space; running cluster needs headroom for WAL and temp files. Fix: Monitor filesystem % used; keep WAL on separate volume.

Alternatives

FAQs

Related

• Installation Basics - package installs before initdb
• postgresql.conf Essentials - tune after first boot
• pg_hba.conf & Authentication - allow connections
• Systemd & Service Management - start the new cluster

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, and PostGIS 3.5+.