Configuration

This page is a thumbnail index of PostgreSQL's configuration surface. The full reference is doc/src/sgml/config.sgml and the runtime view pg_settings. Source for the GUC infrastructure: src/backend/utils/misc/guc.c plus the per-category tables in guc_tables.c and guc_*.c files.

Where parameters come from

A backend's view of a parameter is built up from several sources, with later layers overriding earlier:

1. Compiled-in default.
2. postgresql.conf.
3. postgresql.auto.conf (written by ALTER SYSTEM).
4. Server command line (-c name=value).
5. ALTER DATABASE / ROLE ... SET.
6. Connection-time parameter (PGOPTIONS, options in connection string).
7. Per-session SET and SET LOCAL.

The "context" of a parameter — whether it can be changed at runtime, only at server start, only by superuser, etc. — is recorded in its GUC table entry.

Connection and authentication

GUC	Default	Effect
listen_addresses	localhost	Network interfaces to bind.
port	5432	TCP port.
max_connections	100	Maximum concurrent backends.
superuser_reserved_connections	3	Slots reserved for superuser.
unix_socket_directories	/tmp (varies)	Directory for Unix socket.
ssl	off	Enable SSL.
ssl_cert_file, ssl_key_file, ssl_ca_file	—	Paths.
password_encryption	scram-sha-256	Hash for new passwords.

Authentication rules are in pg_hba.conf (host-based authentication), one connection-matching line per row. Cluster-wide users live in pg_authid (shared catalog).

Memory

GUC	Default	Notes
shared_buffers	128 MB	Per-cluster shared memory for the buffer pool. Allocate ~25% of RAM for typical OLTP.
work_mem	4 MB	Per-operation working memory (one Sort, one HashJoin, etc., gets this much before spilling).
maintenance_work_mem	64 MB	Larger limit for maintenance ops (CREATE INDEX, VACUUM).
effective_cache_size	4 GB	Planner hint about OS + shared cache combined. Doesn't allocate anything.
temp_buffers	8 MB	Per-backend buffer for temp tables.
wal_buffers	-1 (auto: 1/32 of shared_buffers)	WAL write buffer.

WAL and durability

GUC	Default	Notes
wal_level	replica	minimal, replica, logical. Determines what WAL records are emitted.
synchronous_commit	on	When to consider a commit durable. off trades latency for the chance of losing the last few transactions.
fsync	on	Don't turn off in production.
wal_compression	off	Compress full-page images.
wal_writer_delay	200 ms	How often WAL writer flushes.
commit_delay, commit_siblings	0, 5	Group-commit tuning.
max_wal_size, min_wal_size	1 GB, 80 MB	Triggers checkpoints.
checkpoint_timeout	5 min	Maximum time between checkpoints.
checkpoint_completion_target	0.9	Spread checkpoint I/O over this fraction of checkpoint_timeout.

Replication

GUC	Default	Notes
max_wal_senders	10	Limit of streaming/walsender backends.
max_replication_slots	10	Limit of replication slots.
wal_keep_size	0	Min WAL retention beyond replication slots.
synchronous_standby_names	(empty)	Comma-separated list (or ANY n (...)) of standbys whose ack is required for synchronous commit.
hot_standby	on	On a standby, allow read-only queries during recovery.
hot_standby_feedback	off	Standby reports xmin upstream.
max_logical_replication_workers	4	Apply workers per cluster.
max_sync_workers_per_subscription	2	Initial-sync workers per subscription.

Query planner

GUC	Default	Notes
random_page_cost	4.0	Lower for SSDs (often 1.1).
seq_page_cost	1.0	Anchor of the cost model.
cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost	0.01, 0.005, 0.0025	Per-row CPU costs.
effective_io_concurrency	1	Hint for prefetching during bitmap scans.
default_statistics_target	100	Sample size for ANALYZE.
max_parallel_workers_per_gather	2	Workers per parallel query.
max_parallel_workers	8	Cluster-wide cap.
enable_* flags (e.g., enable_seqscan)	on	Disable to force the planner away from a particular plan shape. Useful for diagnosing, not a tuning lever.
jit	on	Enable JIT compilation for expensive expressions.

Logging

GUC	Default	Notes
logging_collector	off	Run a syslogger child.
log_destination	stderr	csvlog, jsonlog, syslog are alternatives.
log_directory, log_filename, log_rotation_*	—	Where logs go and rotation policy.
log_min_messages	warning	Severity threshold for the server log.
log_min_error_statement	error	Statement-level threshold.
log_min_duration_statement	-1	Log statements that took longer than this. Set to 0 to log all.
log_line_prefix	varies	Format of the per-line prefix (%t %p %u %d ...).
log_statement	none	none, ddl, mod, all.
log_lock_waits	off	Log when a backend waits >deadlock_timeout for a lock.

Autovacuum

GUC	Default	Notes
autovacuum	on	Don't turn off.
autovacuum_vacuum_threshold, _scale_factor	50, 0.2	Trigger thresholds.
autovacuum_analyze_threshold, _scale_factor	50, 0.1	Same for ANALYZE.
autovacuum_max_workers	3	Concurrent vacuum workers.
autovacuum_naptime	1 min	Sleep between cycles.
vacuum_cost_delay, _limit	varies	Throttling.

Per-table overrides live in pg_class.reloptions.

Statistics, monitoring, telemetry

GUC	Default	Notes
track_activities, track_counts, track_io_timing, track_wal_io_timing	varies	Enable various stat collections.
pg_stat_statements.max, .track	5000, top	Configures the contrib module.
compute_query_id	auto	Generate a stable hash for queries (used by pg_stat_statements).

Common gotchas

• shared_buffers requires a restart, not a reload. So do max_connections, max_locks_per_transaction, and most parameters that allocate shared memory.
• checkpoint_completion_target was raised from 0.5 to 0.9 in 14. Older docs/blog posts may suggest 0.5.
• work_mem is per-operation, not per-query and not per-connection. A single query with three sorts in parallel can use 3 × work_mem. With parallel workers, multiply by the number of workers.
• random_page_cost = 4.0 is wrong on SSD. Lower it to 1.0–1.5.
• effective_io_concurrency is consulted only for bitmap heap scans on Linux/FreeBSD/macOS; it doesn't issue any prefetch on Windows.

Inspecting the live config

SHOW all;                                           -- everything
SELECT name, setting, source FROM pg_settings;      -- structured
SELECT * FROM pg_settings WHERE source != 'default';-- non-defaults
SELECT pg_reload_conf();                            -- reload from postgresql.conf
ALTER SYSTEM SET work_mem = '8MB';                  -- writes postgresql.auto.conf

For full documentation, see the official config docs and doc/src/sgml/config.sgml.