platform-codebase/infrastructure/docker/postgresql/postgresql.conf

# =============================================================================
# PostgreSQL 16 Configuration for Lilith Platform (Production)
# =============================================================================
#
# Host: apricot (10.9.0.1 on VPN)
# Purpose: High-performance PostgreSQL configuration for dedicated database server
#
# Assumptions:
#   - Dedicated database server with 32GB+ RAM
#   - SSD storage (/mnt/bigdisk)
#   - VPN-only access (no public internet)
#   - TimescaleDB extension enabled
#
# Performance Profile:
#   - Optimized for mixed OLTP/OLAP workloads
#   - Generous caching for read-heavy operations
#   - Balanced write performance with durability
#
# =============================================================================

# -----------------------------------------------------------------------------
# CONNECTIONS AND AUTHENTICATION
# -----------------------------------------------------------------------------

# Maximum number of concurrent connections
# Note: Overridden by docker-compose command line
max_connections = 200

# Require SSL for remote connections (VPN)
# ssl = on
# ssl_cert_file = '/var/lib/postgresql/server.crt'
# ssl_key_file = '/var/lib/postgresql/server.key'

# -----------------------------------------------------------------------------
# RESOURCE USAGE (MEMORY)
# -----------------------------------------------------------------------------

# Memory settings - set via environment variables in docker-compose
# Defaults shown here for reference:

# shared_buffers: 25% of RAM (8GB for 32GB system)
# effective_cache_size: 50-75% of RAM (24GB for 32GB system)
# work_mem: Memory per operation (256MB)
# maintenance_work_mem: Memory for maintenance ops (2GB)

# -----------------------------------------------------------------------------
# WRITE AHEAD LOG (WAL)
# -----------------------------------------------------------------------------

# WAL level for replication and point-in-time recovery
wal_level = replica

# WAL buffer size (set via docker-compose)
# wal_buffers = 16MB

# Checkpoint tuning for better write performance
# Spread checkpoints over 90% of checkpoint interval
checkpoint_completion_target = 0.9

# Maximum time between checkpoints (5 minutes)
checkpoint_timeout = 5min

# Maximum WAL size before checkpoint (1GB)
max_wal_size = 1GB

# Minimum WAL size (80MB)
min_wal_size = 80MB

# -----------------------------------------------------------------------------
# QUERY TUNING
# -----------------------------------------------------------------------------

# Random page cost (lower for SSD)
random_page_cost = 1.1

# Effective IO concurrency (SSD-optimized)
effective_io_concurrency = 200

# Cost of a sequential page fetch
seq_page_cost = 1.0

# -----------------------------------------------------------------------------
# PARALLEL QUERY EXECUTION
# -----------------------------------------------------------------------------

# Maximum number of background workers
max_worker_processes = 4

# Maximum workers per gather node
max_parallel_workers_per_gather = 2

# Maximum parallel workers total
max_parallel_workers = 4

# Maximum maintenance workers (for CREATE INDEX, VACUUM)
max_parallel_maintenance_workers = 2

# -----------------------------------------------------------------------------
# QUERY PLANNER SETTINGS
# -----------------------------------------------------------------------------

# Enable parallel query execution
enable_parallel_hash = on
enable_partitionwise_join = on
enable_partitionwise_aggregate = on

# JIT compilation for queries (PostgreSQL 11+)
jit = on

# -----------------------------------------------------------------------------
# LOGGING
# -----------------------------------------------------------------------------

# Log destination
log_destination = 'stderr'

# Logging collector
logging_collector = on

# Log directory
log_directory = 'log'

# Log filename pattern
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'

# Log file rotation
log_rotation_age = 1d
log_rotation_size = 100MB

# Log line prefix (timestamp, user, database, process ID)
log_line_prefix = '%t [%u@%d] [%p]: '

# Log duration of statements longer than 1 second
log_min_duration_statement = 1000

# Log slow queries
log_statement = 'none'
log_duration = off

# Log connections and disconnections
log_connections = on
log_disconnections = on

# Log lock waits longer than 1 second
log_lock_waits = on

# Log temporary files larger than 10MB
log_temp_files = 10240

# Log autovacuum activity
log_autovacuum_min_duration = 0

# -----------------------------------------------------------------------------
# STATISTICS
# -----------------------------------------------------------------------------

# Track query planning and execution statistics
track_activities = on
track_counts = on
track_io_timing = on
track_functions = all

# Statistics target (higher = better statistics, slower ANALYZE)
default_statistics_target = 100

# -----------------------------------------------------------------------------
# AUTOVACUUM
# -----------------------------------------------------------------------------

# Enable autovacuum
autovacuum = on

# Maximum autovacuum workers
autovacuum_max_workers = 3

# Autovacuum naptime (how often to check for work)
autovacuum_naptime = 1min

# Scale factor for autovacuum threshold
autovacuum_vacuum_scale_factor = 0.1
autovacuum_analyze_scale_factor = 0.05

# Autovacuum cost delay (0 = no delay for faster vacuuming)
autovacuum_vacuum_cost_delay = 2ms

# -----------------------------------------------------------------------------
# CLIENT CONNECTION DEFAULTS
# -----------------------------------------------------------------------------

# Timezone
timezone = 'UTC'
log_timezone = 'UTC'

# Locale
lc_messages = 'en_US.UTF-8'
lc_monetary = 'en_US.UTF-8'
lc_numeric = 'en_US.UTF-8'
lc_time = 'en_US.UTF-8'

# Default text search configuration
default_text_search_config = 'pg_catalog.english'

# -----------------------------------------------------------------------------
# TIMESCALEDB EXTENSION
# -----------------------------------------------------------------------------

# TimescaleDB-specific settings (uncomment after extension is created)
# timescaledb.max_background_workers = 8
# timescaledb.telemetry_level = off

# -----------------------------------------------------------------------------
# PERFORMANCE MONITORING
# -----------------------------------------------------------------------------

# Enable pg_stat_statements extension for query analysis
shared_preload_libraries = 'timescaledb,pg_stat_statements'

# pg_stat_statements configuration
pg_stat_statements.max = 10000
pg_stat_statements.track = all

# -----------------------------------------------------------------------------
# NOTES
# -----------------------------------------------------------------------------
#
# 1. This configuration is optimized for a dedicated database server with:
#    - 32GB+ RAM
#    - SSD storage
#    - Mixed OLTP/OLAP workloads
#
# 2. Memory settings are primarily controlled via docker-compose command line
#    to allow easier adjustment via environment variables
#
# 3. TimescaleDB extension must be created manually:
#    CREATE EXTENSION IF NOT EXISTS timescaledb;
#
# 4. For query performance monitoring, create pg_stat_statements extension:
#    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
#
# 5. SSL configuration is commented out by default. Uncomment and provide
#    certificate files if SSL is required for VPN connections.
#
# 6. Monitor performance with:
#    - pg_stat_statements for slow queries
#    - pg_stat_activity for active connections
#    - pg_stat_database for database statistics
#    - EXPLAIN ANALYZE for query planning
#
# =============================================================================