Systemd & Service Management

Production PostgreSQL on Linux runs under systemd (or an equivalent init). Knowing start, stop, reload, and status maps directly to incident response and safe deploys.

Recipe

# systemd (Debian/Ubuntu package names vary)
sudo systemctl start postgresql@18-main
sudo systemctl status postgresql@18-main
sudo systemctl reload postgresql@18-main
 
# pg_ctl equivalents (any install)
sudo -u postgres pg_ctl -D /var/lib/postgresql/18/main start
sudo -u postgres pg_ctl -D /var/lib/postgresql/18/main reload
sudo -u postgres pg_ctl -D /var/lib/postgresql/18/main status

When to reach for this: Bootstrapping a host, applying pg_hba.conf changes, or recovering from a failed stop during maintenance.

Working Example

# Inspect unit and environment
systemctl cat postgresql@18-main
systemctl show postgresql@18-main -p Environment -p ExecStart
 
# Graceful reload after config change
sudo systemctl reload postgresql@18-main
 
# Confirm reload picked up hba
sudo -u postgres psql -c "SELECT pg_reload_conf();"

# Override fragment: /etc/systemd/system/postgresql@18-main.service.d/override.conf
[Service]
Environment=PGDATA=/data/pgdata
TimeoutStartSec=300
TimeoutStopSec=300

sudo systemctl daemon-reload
sudo systemctl restart postgresql@18-main

What this demonstrates:

• reload sends SIGHUP - applies pg_hba.conf and many GUCs without dropping connections
• daemon-reload required after unit file edits
• TimeoutStopSec gives checkpoints time on large shared_buffers systems

Deep Dive

systemd vs pg_ctl Mapping

Stop Modes

# smart - wait for clients (default)
pg_ctl stop -D $PGDATA -m smart
 
# fast - rollback active transactions, disconnect clients
pg_ctl stop -D $PGDATA -m fast
 
# immediate - crash-like shutdown, recovery on next start
pg_ctl stop -D $PGDATA -m immediate

• Production maintenance: prefer fast unless you need smart drain.
• immediate risks longer crash recovery - use only when fast hangs.

Enable at Boot

sudo systemctl enable postgresql@18-main
sudo systemctl is-enabled postgresql@18-main

• enable creates symlinks for multi-user.target.
• Cloud VMs with ephemeral disks still enable the unit - data dir must persist separately.

Logs

journalctl -u postgresql@18-main -f
journalctl -u postgresql@18-main --since "1 hour ago" -p err

• Package installs often log to stderr captured by journald.
• Also check log_directory in postgresql.conf for CSV/json file logs.

Gotchas

• Restart instead of reload for postmaster GUCs - shared_buffers changes need restart; reload silently keeps old value with pending_restart. Fix: SELECT name FROM pg_settings WHERE pending_restart;
• Wrong PGDATA in unit - Multiple clusters on one host need distinct instances (postgresql@18-main). Fix: systemctl cat and SHOW data_directory; must agree.
• Stop timeout too short - systemd kills postgres mid-checkpoint. Fix: Raise TimeoutStopSec to 300s+ on large systems.
• Running pg_ctl as root - Server refuses root-owned operations. Fix: sudo -u postgres pg_ctl ...
• reload during heavy DDL - Reload itself is safe, but restart during migration is not. Fix: Use reload for hba; schedule restart in maintenance window.

Alternatives

FAQs

Related

• postgresql.conf Essentials - which GUCs need restart
• pg_hba.conf & Authentication - reload after hba edits
• initdb & Data Directory - PGDATA path in unit files

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+.