Reload vs Restart

Know which configuration changes need a full restart and which take effect immediately — and use pending_restart to verify

Not all configuration changes are equal. Some take effect the instant the server receives a reload signal. Others require a full shutdown and restart because they allocate shared memory or set up network listeners at startup time — things that cannot be changed on a running process.\n\nThe pg_settings.context column tells you which category a parameter belongs to. The pg_settings.pending_restart column is your safety check: if it is true, a parameter has been changed in the config file but the running server is still using the old value. That is a common source of "why isn't my change working?" confusion.\n\nIn production, minimising restarts matters. A reload is instant and zero-downtime. A restart disconnects all clients. Knowing the difference lets you schedule changes appropriately.

How to Apply a Configuration Change

-- Step 1: Make the change
ALTER SYSTEM SET work_mem = '32MB';

-- Step 2: Check the context
SELECT name, context FROM pg_settings WHERE name = 'work_mem';
-- context = 'user' → reload is sufficient

-- Step 3: Apply it
SELECT pg_reload_conf();   -- for sighup/user/superuser context

-- If context = 'postmaster': schedule a restart instead

Finding Parameters That Need a Restart

SELECT name, setting, unit, pending_restart
FROM pg_settings
WHERE pending_restart = true;

If this returns rows, those parameters have been changed in the config file but the running server is still using the old values. A restart is required to activate them.

Common Parameters by Context

Reload-only (sighup):

Restart required (postmaster):

pending_restart

A boolean column in pg_settings that is true when a parameter has been changed in a configuration file (postgresql.conf or postgresql.auto.conf) but cannot take effect until the server is restarted. This happens for postmaster-context parameters. Always query WHERE pending_restart = true after editing config files to identify changes that still need a restart.

SIGHUP

A Unix signal sent to the PostgreSQL postmaster process to trigger a configuration reload. pg_reload_conf() sends SIGHUP from inside SQL. pg_ctl reload sends it from the command line. On receiving SIGHUP, the postmaster re-reads postgresql.conf, postgresql.auto.conf, pg_hba.conf, and pg_ident.conf, then propagates changes to all worker processes for sighup-context parameters.

🔌 Connect as postgres

Connect to the postgres database as the postgres superuser.

psql -U postgres

SET psql (18.4) Type "help" for help. postgres=#

📋 List postmaster-Context Parameters

Query pg_settings for all parameters that require a restart to change (context = 'postmaster'). These are the parameters you must schedule a maintenance window for.

SELECT name, setting, unit FROM pg_settings WHERE context = 'postmaster' ORDER BY name LIMIT 12;

name | setting | unit -------------------------------------+--------------------------------+------ archive_mode | off | autovacuum_freeze_max_age | 200000000 | autovacuum_multixact_freeze_max_age | 400000000 | autovacuum_worker_slots | 16 | bonjour | off | bonjour_name | | cluster_name | | commit_timestamp_buffers | 16 | 8kB config_file | /var/lib/postgresql/18/data/postgresql.conf | data_directory | /var/lib/postgresql/18/data | data_sync_retry | off | debug_io_direct | | (12 rows)

✅ Demonstrate the Reload-Only Path: work_mem

work_mem has context=user, so it only ever needs a reload. Raise it to 24MB with ALTER SYSTEM, reload, and confirm it took effect immediately with no pending restart.

ALTER SYSTEM SET work_mem = '24MB';
SELECT pg_reload_conf();
SELECT name, setting, unit, pending_restart FROM pg_settings WHERE name = 'work_mem';

ALTER SYSTEM pg_reload_conf ---------------- t (1 row) name | setting | unit | pending_restart ----------+---------+------+----------------- work_mem | 24576 | kB | f (1 row)

⏳ Demonstrate the Restart-Required Path: max_connections

max_connections has context=postmaster. Raise it to 200 with ALTER SYSTEM, reload anyway, and watch pending_restart flip to true — proof the reload alone could not apply it.

ALTER SYSTEM SET max_connections = 200;
SELECT pg_reload_conf();
SELECT name, setting, unit, pending_restart FROM pg_settings WHERE name = 'max_connections';

ALTER SYSTEM pg_reload_conf ---------------- t (1 row) name | setting | unit | pending_restart -----------------+---------+------+----------------- max_connections | 10 | | t (1 row)

⏳ Check for Pending Restarts

Query pg_settings for every parameter that has been changed in config files but is waiting for a restart. max_connections should now appear — this is the definitive check after any configuration change.

SELECT name, setting, unit FROM pg_settings WHERE pending_restart = true;

name | setting | unit -----------------+---------+------ max_connections | 10 | (1 row)

🕐 Record the Start Time

Run pg_postmaster_start_time() to record when the server started. In the next lab you will restart the server to apply max_connections and compare this value to confirm the cycle happened.

SELECT pg_postmaster_start_time();

pg_postmaster_start_time -------------------------------------- 2026-06-26 16:02:25.102021+00 (1 row)

Lab 2.1.4 complete. You can now apply configuration changes safely:\n\n\n work_mem (sighup) → reload only — pending_restart stayed false\n max_connections (postmaster) → reload not enough — pending_restart became true\n pending_restart check → confirm what is still waiting\n pg_postmaster_start_time → verify restarts happened\n

Enable JavaScript to run the live terminal and track your progress.