pg_doorman.yaml

# pg_doorman YAML configuration
# ============================================================================
# IMPORTANT: Use ONLY ONE configuration file format (YAML or TOML), not both.
# YAML format (.yaml, .yml) is recommended for new configurations.
# TOML format (.toml) is supported for backward compatibility.
# The format is automatically detected based on the file extension.
# ============================================================================
#
# HUMAN-READABLE VALUES
# ============================================================================
# pg_doorman supports human-readable formats for duration and byte size values.
# Both numeric values (for backward compatibility) and string formats are supported.
#
# Duration formats:
#   - Plain numbers: interpreted as milliseconds (e.g., 5000 = 5 seconds)
#   - "Nms" : milliseconds (e.g., "100ms")
#   - "Ns"  : seconds (e.g., "5s" = 5000 milliseconds)
#   - "Nm"  : minutes (e.g., "5m" = 300000 milliseconds)
#   - "Nh"  : hours (e.g., "1h" = 3600000 milliseconds)
#   - "Nd"  : days (e.g., "1d" = 86400000 milliseconds)
#
# Byte size formats:
#   - Plain numbers: interpreted as bytes (e.g., 1048576 = 1 MB)
#   - "NB"  : bytes (e.g., "1024B")
#   - "NK" or "NKB" : kilobytes (e.g., "1K" or "1KB" = 1024 bytes)
#   - "NM" or "NMB" : megabytes (e.g., "1M" or "1MB" = 1048576 bytes)
#   - "NG" or "NGB" : gigabytes (e.g., "1G" or "1GB" = 1073741824 bytes)
#
# Examples:
#   connect_timeout: "3s"        # instead of 3000
#   idle_timeout: "10m"          # instead of 600000
#   max_memory_usage: "256MB"    # instead of 268435456
# ============================================================================

# Include additional configuration files.
# Files are merged in order, allowing modular configuration.
include:
  # files:
  #   - "/etc/pg_doorman/pools.yaml"
  #   - "/etc/pg_doorman/hba.yaml"

# ############################################################################
# GENERAL SETTINGS
# ############################################################################
general:
  # --------------------------------------------------------------------------
  # Network Settings
  # --------------------------------------------------------------------------

  # Listen host for incoming connections (IPv4 only).
  # Default: "0.0.0.0"
  host: "0.0.0.0"

  # Listen port for incoming connections.
  # Default: 5432
  port: 6432

  # TCP backlog for incoming connections.
  # A value of zero sets max_connections as the TCP backlog value.
  # Default: 0
  backlog: 0

  # --------------------------------------------------------------------------
  # Connection Timeouts
  # --------------------------------------------------------------------------

  # Timeout for establishing a new connection to PostgreSQL. Similar to PgBouncer's server_connect_timeout.
  # Supports human-readable format: "3s", "3000ms", or 3000 (milliseconds)
  # Default: "3s" (3000 ms)
  connect_timeout: "3s"

  # How long a client waits for a server connection before getting an error.
  # Applies when all connections in the pool are busy.
  # Similar to PgBouncer's query_wait_timeout.
  # Supports human-readable format: "5s", "5000ms", or 5000 (milliseconds)
  # Default: "5s" (5000 ms)
  query_wait_timeout: "5s"

  # Close a server connection that has been idle longer than this.
  # Only applies to connections that served at least one client request.
  # Prewarmed connections that were never used are not affected (use server_lifetime for those).
  # Set to 0 to disable. Similar to PgBouncer's server_idle_timeout.
  # Supports human-readable format: "10m", "600000ms", or 600000 (milliseconds)
  # Default: "10m" (600000 ms)
  idle_timeout: "10m"

  # Maximum age of a server connection. Closed when idle, not mid-transaction.
  # Applies to all connections including prewarmed ones that were never used.
  # Set to 0 to disable. Similar to PgBouncer's server_lifetime.
  # Supports human-readable format: "20m", "1200000ms", or 1200000 (milliseconds)
  # Default: "20m" (1200000 ms)
  server_lifetime: "20m"

  # Interval for checking and closing idle connections.
  # Supports human-readable format: "30s", "30000ms", or 30000 (milliseconds)
  # Default: "30s" (30000 ms)
  retain_connections_time: "30s"

  # Maximum number of idle connections to close per retain cycle.
  # 0 means unlimited (close all idle connections that exceed timeout).
  # Default: 3
  retain_connections_max: 3

  # Time after which an idle server connection should be checked before being
  # given to a client. This helps detect dead connections caused by PostgreSQL
  # restart, network issues, or server-side idle timeouts.
  # 0 means disabled (no check).
  # Supports human-readable format: "60s", "60000ms", or 60000 (milliseconds)
  # Default: "60s"
  server_idle_check_timeout: "60s"

  # Time to wait for active transactions to finish during graceful shutdown.
  # Supports human-readable format: "10s", "10000ms", or 10000 (milliseconds)
  # Default: "10s" (10000 ms)
  shutdown_timeout: "10s"

  # Timeout for COPY data operations.
  # Supports human-readable format: "15s", "15000ms", or 15000 (milliseconds)
  # Default: "15s" (15000 ms)
  proxy_copy_data_timeout: "15s"

  # --------------------------------------------------------------------------
  # TCP Settings
  # --------------------------------------------------------------------------

  # TCP keepalive settings (in seconds).
  # Keepalive is enabled by default and overwrites OS defaults.
  # Default: 5
  tcp_keepalives_idle: 5
  # Default: 5
  tcp_keepalives_interval: 5
  # Default: 5
  tcp_keepalives_count: 5

  # TCP SO_LINGER setting.
  # By default, pg_doorman sends RST instead of keeping the connection open.
  # Default: 0
  tcp_so_linger: 0

  # Enable TCP_NODELAY to disable Nagle's algorithm for lower latency.
  # Default: true
  tcp_no_delay: true

  # TCP_USER_TIMEOUT for client connections (in seconds).
  # Helps detect dead connections faster when data remains unacknowledged.
  # Only supported on Linux. Set to 0 to disable.
  # Default: 60
  tcp_user_timeout: 60

  # Buffer size for read/write operations when connecting via unix socket.
  # Supports human-readable format: "1MB", "1M", or 1048576 (bytes)
  # Default: "1MB" (1048576 bytes)
  unix_socket_buffer_size: "1MB"

  # Directory for Unix socket listener. Creates .s.PGSQL.<port> file. Use psql -h <dir> or pgbench -h <dir> to connect.
  # When set, pg_doorman also accepts connections via Unix socket (.s.PGSQL.<port>).
  # unix_socket_dir: "/var/run/pg_doorman"

  # Permission mode applied to the .s.PGSQL.<port> socket file after bind.
  # Octal string. Only the lowest 9 bits (0o777) are honored.
  # Default: "0600"
  unix_socket_mode: "0600"

  # --------------------------------------------------------------------------
  # Connection Limits
  # --------------------------------------------------------------------------

  # Maximum number of clients that can connect simultaneously.
  # When reached, clients receive error code 53300: "sorry, too many clients already"
  # Default: 8192
  max_connections: 8192

  # Maximum number of server connections that can be created concurrently.
  # Uses a semaphore to limit parallel connection creation.
  # Default: 4
  max_concurrent_creates: 4

  # Memory limit for in-flight query buffers across all connections.
  # When exceeded, new queries are rejected with an error until memory drops below the limit.
  # Supports human-readable format: "256MB", "256M", or 268435456 (bytes)
  # Default: "256MB" (268435456 bytes)
  max_memory_usage: "256MB"

  # --------------------------------------------------------------------------
  # Connection Scaling
  # --------------------------------------------------------------------------

  # Warm pool ratio (0-100, percentage).
  # Connections below this threshold of max_size are created immediately.
  # Above this threshold, anticipation wait + bounded burst is applied.
  # Default: 20
  scaling_warm_pool_ratio: 20

  # Number of fast retries with yield_now() before the anticipation wait.
  # Higher values reduce latency on micro-races but increase CPU usage.
  # Default: 10
  scaling_fast_retries: 10

  # Hard cap on concurrent server connection creates per pool.
  # Anti-thundering-herd: tasks above this limit wait on a Notify
  # for either an idle return or a create completion. Must be >= 1.
  # Default: 2
  scaling_max_parallel_creates: 2
  # --------------------------------------------------------------------------
  # Logging
  # --------------------------------------------------------------------------

  # Log client connections for monitoring.
  # Default: true
  log_client_connections: true

  # Log client disconnections for monitoring.
  # Default: true
  log_client_disconnections: true

  # Syslog program name. When specified, pg_doorman sends messages to syslog.
  # Comment out to log to stdout.
  # Default: None
  # syslog_prog_name: "pg_doorman"

  # --------------------------------------------------------------------------
  # Worker Settings
  # --------------------------------------------------------------------------

  # Tokio worker threads for handling client connections.
  # Set to CPU core count for best throughput. Exceeding core count gives no benefit.
  # Default: 4
  worker_threads: 4

  # Bind each worker thread to a separate CPU core. By default, worker threads are not bound to any specific CPU.
  # Default: false
  worker_cpu_affinity_pinning: false

  # Tokio runtime settings (advanced, change only if you understand the implications).
  # Modern tokio versions handle these well by default, so these parameters are optional.
  # Uncomment only if you need to override tokio's defaults.

  # Stack size for each worker thread.
  # Supports human-readable format: "8MB", "8M", or 8388608 (bytes)
  # Default: not set (uses tokio's default)
  # worker_stack_size: "8MB"

  # Maximum number of threads for blocking operations.
  # Default: not set (uses tokio's default)
  # max_blocking_threads: 64

  # Controls how often the scheduler checks the global task queue.
  # Default: not set (uses tokio's default)
  # tokio_global_queue_interval: 5

  # Controls how often the scheduler checks for external events (I/O, timers).
  # Default: not set (uses tokio's default)
  # tokio_event_interval: 1

  # --------------------------------------------------------------------------
  # Pool Behavior
  # --------------------------------------------------------------------------

  # Server selection strategy in transaction mode.
  # false = LRU (reuse most recent connection) — better cache locality
  # true  = Round Robin (rotate across connections) — more even load
  # Default: false
  server_round_robin: false

  # Track and replay a subset of session parameters on each new backend in transaction mode.
  # Tracked parameters: client_encoding, DateStyle, TimeZone, standard_conforming_strings, application_name.
  # Adds a SET roundtrip per checkout. Disabled by default.
  # If you only need application_name, use the pool-level application_name setting instead.
  # Default: false
  sync_server_parameters: false

  # DataRow messages larger than this threshold are streamed to the client in small chunks
  # instead of being buffered entirely in memory. Prevents memory spikes on large rows.
  # Supports human-readable format: "1MB", "1M", or 1048576 (bytes)
  # Default: "1MB" (1048576 bytes)
  message_size_to_be_stream: "1MB"

  # Query intercepted by pg_doorman and answered locally (never reaches PostgreSQL).
  # Used by load balancers and monitoring to check if the pooler is alive.
  # Default: ";"
  pooler_check_query: ";"

  # --------------------------------------------------------------------------
  # Prepared Statements
  # --------------------------------------------------------------------------

  # Enable caching of prepared statements.
  # Default: true
  prepared_statements: true

  # Cache size for prepared statements at the pool level (shared across clients).
  # Default: 8192
  prepared_statements_cache_size: 8192

  # Per-backend prepared statement LRU size. When unset, inherits prepared_statements_cache_size.
  # Lets operators bound DOORMAN_<N> rows on a single PostgreSQL backend without shrinking the pool-level cache.
  # Default: not set (inherits prepared_statements_cache_size)
  # server_prepared_statements_cache_size: 8192

  # Per-client Anonymous prepared-statement LRU size. When unset, inherits prepared_statements_cache_size.
  # Bounds the Anonymous part of the per-client cache; the Named part is always unbounded.
  # Set to 0 to disable the LRU and use an unlimited map.
  # Default: not set (inherits prepared_statements_cache_size)
  # client_anonymous_prepared_cache_size: 8192

  # How often (seconds) the query interner runs its mark-and-sweep GC.
  # The sweep tick is gc_interval / 4 so a marked entry has a quarter-interval
  # to be touched (and unmarked) before the next eviction pass.
  # Default: 60
  query_interner_gc_interval_seconds: 60

  # Idle time (seconds) after which an anonymous interner entry becomes
  # eligible for eviction. 0 disables TTL eviction entirely.
  # Default: 60
  query_interner_anon_idle_ttl_seconds: 60

  # --------------------------------------------------------------------------
  # Admin Console
  # --------------------------------------------------------------------------

  # Admin username for the virtual admin database (pgdoorman).
  # Default: "admin"
  admin_username: "admin"

  # Admin password for the virtual admin database.
  # IMPORTANT: Change this in production!
  # Default: "admin"
  admin_password: "admin"

  # --------------------------------------------------------------------------
  # TLS Settings (Client-facing)
  # --------------------------------------------------------------------------

  # Path to the TLS certificate file for incoming client connections.
  # Must be used together with tls_private_key.
  # tls_certificate: "/etc/pg_doorman/server.crt"

  # Path to the TLS private key file for incoming client connections.
  # Must be used together with tls_certificate.
  # tls_private_key: "/etc/pg_doorman/server.key"

  # Path to the CA certificate for client certificate verification.
  # Used with tls_mode = "verify-full"
  # tls_ca_cert: "/etc/pg_doorman/ca.crt"

  # TLS mode for incoming connections:
  # - "allow"       : TLS allowed but not required (default)
  # - "disable"     : TLS not allowed
  # - "require"     : TLS required
  # - "verify-full" : TLS required with client certificate verification
  # Default: "allow"
  tls_mode: "allow"

  # Limit simultaneous TLS session creation attempts.
  # Useful for applications with many connections at startup ("hot start").
  # 0 = no limit
  # Default: 0
  tls_rate_limit_per_second: 0

  # --------------------------------------------------------------------------
  # TLS Settings (Server-facing)
  # --------------------------------------------------------------------------

  # TLS mode for outgoing connections to PostgreSQL servers:
  # - "allow"       : Try plain first; if server rejects, retry with TLS (default)
  # - "disable"     : TLS not used
  # - "prefer"      : TLS used if server supports it
  # - "require"     : TLS required, certificate not verified
  # - "verify-ca"   : TLS required, server certificate verified against CA
  # - "verify-full" : TLS required, server certificate and hostname verified
  # Default: "allow"
  server_tls_mode: "allow"

  # Path to the CA certificate file for verifying PostgreSQL server certificates.
  # Required when server_tls_mode is "verify-ca" or "verify-full".
  # Default: None
  # server_tls_ca_cert: ""

  # Path to the client TLS certificate for mutual TLS with PostgreSQL servers.
  # Used together with server_tls_private_key.
  # Default: None
  # server_tls_certificate: ""

  # Path to the private key for the client TLS certificate.
  # Used together with server_tls_certificate.
  # Default: None
  # server_tls_private_key: ""

  # --------------------------------------------------------------------------
  # Daemon Mode
  # --------------------------------------------------------------------------

  # PID file path for daemon mode.
  # Setting this enables daemon mode. Comment out for foreground mode with `-d`.
  # Default: "/tmp/pg_doorman.pid"
  # daemon_pid_file: "/tmp/pg_doorman.pid"

  # --------------------------------------------------------------------------
  # Access Control (Legacy)
  # --------------------------------------------------------------------------

  # Simple IP-based access control list.
  # List of IP networks allowed to connect (e.g., "10.0.0.0/8").
  # Empty list allows all addresses.
  # For more advanced access control, use pg_hba instead.
  # Default: []
  hba: []

  # --------------------------------------------------------------------------
  # Access Control (pg_hba - Recommended)
  # --------------------------------------------------------------------------

  # PostgreSQL-style pg_hba.conf rules for client authentication.
  # Supports three formats:
  #
  # 1. Inline multiline string:
  #    pg_hba: |
  #      host all all 0.0.0.0/0 md5
  #      hostssl all all 10.0.0.0/8 scram-sha-256
  #      local all all trust
  #
  # 2. Path to external file:
  #    pg_hba:
  #      path: "/etc/pg_doorman/pg_hba.conf"
  #
  # 3. Inline content in map format:
  #    pg_hba:
  #      content: "host all all 127.0.0.1/32 trust"
  #
  # Rule format: TYPE DATABASE USER ADDRESS METHOD
  # Types: local, host, hostssl, hostnossl
  # Methods: trust, md5, scram-sha-256, reject
  #
  # Trust behavior: when a matching rule uses 'trust', pg_doorman accepts
  # the connection without asking for a password, even if the user has
  # an MD5 or SCRAM password configured.
  #
  # Example pg_hba rules:
  # pg_hba: |
  #   # Allow local connections without password
  #   local all all trust
  #   # Require SSL and SCRAM for internal network
  #   hostssl all all 10.0.0.0/8 scram-sha-256
  #   # Allow MD5 auth from anywhere
  #   host all all 0.0.0.0/0 md5
  #   # Reject all other connections
  #   host all all 0.0.0.0/0 reject

# ############################################################################
# WEB UI / METRICS
# ############################################################################
web:
  # Enable Prometheus metrics exporter.
  # Default: false
  enabled: false

  # Host for the metrics HTTP endpoint.
  # Default: "0.0.0.0"
  host: "0.0.0.0"

  # Port for the metrics HTTP endpoint.
  # Default: 9127
  port: 9127

  # Enable the web UI.
  # Default: false
  ui: false

  # Allow unauthenticated access to the public read-only API endpoints.
  # Default: false
  ui_anonymous: false

  # Maximum number of log entries held in the in-memory log tap.
  # Default: 8192
  log_tap_max_entries: 8192

  # Enable JWT-based SSO authentication on the web UI.
  # Default: false
  sso_enabled: false

  # URL of the external SSO proxy used by the SPA for the Sign in via SSO redirect.
  # Default: null
  # sso_proxy_url: "https://sso.example.com/oauth2/start"

  # Path to a PEM file with the RSA public key paired with the SSO proxy signing key.
  # Default: null
  # sso_public_key_file: "/etc/pg_doorman/sso-public.pem"

  # Allowed values of the JWT aud claim.
  # Default: []
  # sso_audience: ["pg_doorman"]

  # Allowlist of preferred_username or sub claims.
  # Default: ["*"]
  sso_allowed_users: ["*"]

  # CIDR ranges trusted to set X-Forwarded-For / Forwarded.
  # Default: []
  # trusted_proxies: ["10.0.0.0/8"]

  # JWT claim name that carries the user's group memberships.
  # Default: "groups"
  sso_groups_claim: "groups"

  # Group names that map onto the Admin role.
  # Default: []
  # sso_admin_groups: ["pg-doorman-admins"]

# ############################################################################
# TALOS AUTHENTICATION (Optional)
# ############################################################################
# Talos is an optional authentication mechanism using public key cryptography.
# talos:
#   # List of public key files for Talos authentication.
#   keys:
#     - "/etc/pg_doorman/talos/public-key-1.pem"
#     - "/etc/pg_doorman/talos/public-key-2.pem"
#   # List of databases that use Talos authentication.
#   databases:
#     - "talos_db1"
#     - "talos_db2"

# ############################################################################
# CONNECTION POOLS
# ############################################################################
# Each pool represents a virtual database that clients can connect to.
# Pool names are visible to clients as database names.
pools:

    # Example pool configuration
  exampledb:
    # --------------------------------------------------------------------------
    # Server Connection Settings
    # --------------------------------------------------------------------------

    # PostgreSQL server host (IP address or unix socket directory).
    # Examples: "127.0.0.1", "/var/run/postgresql"
    # Default: "127.0.0.1"
    server_host: "127.0.0.1"

    # PostgreSQL server port.
    # Default: 5432
    server_port: 5432

    # Actual database name on the PostgreSQL server.
    # If not specified, the pool name is used.
    # server_database: "actual_db_name"

    # --------------------------------------------------------------------------
    # Pool Settings
    # --------------------------------------------------------------------------

    # Pooling mode (same as PgBouncer's pool_mode):
    # - "transaction" : backend released after each transaction (recommended)
    # - "session"     : backend held for the entire client session
    # Default: "transaction"
    pool_mode: "transaction"

    # Override global connect_timeout for this pool (in milliseconds).
    # connect_timeout: 5000

    # Override global idle_timeout for this pool (in milliseconds).
    # idle_timeout: 300000

    # Override global server_lifetime for this pool (in milliseconds).
    # server_lifetime: 300000

    # Reset session state (SET, prepared statements, cursors) when returning a connection to pool.
    # ROLLBACK for open transactions is always executed regardless of this setting.
    # Prevents state leaking between clients in transaction mode.
    # Default: true
    cleanup_server_connections: true

    # Override global prepared_statements_cache_size for this pool.
    # prepared_statements_cache_size: 8192

    # Override the per-backend server-level prepared statement LRU for this pool.
    # server_prepared_statements_cache_size: 8192

    # --------------------------------------------------------------------------
    # Connection Scaling Overrides
    # --------------------------------------------------------------------------

    # Override global scaling_warm_pool_ratio for this pool (0-100).
    # scaling_warm_pool_ratio: 30

    # Override global scaling_fast_retries for this pool.
    # scaling_fast_retries: 10

    # --------------------------------------------------------------------------
    # Pool Coordinator (database-level connection limit)
    # --------------------------------------------------------------------------

    # Maximum total server connections to this database across all users.
    # When the limit is reached, idle connections from other users are evicted.
    # 0 = disabled (default): each user pool works independently.
    # max_db_connections: 0

    # Don't evict connections younger than this (milliseconds).
    # Protects freshly created connections from eviction churn
    # between user pools sharing the same database.
    # min_connection_lifetime: 30000

    # Extra connections beyond max_db_connections, used as last resort.
    # Allocated by priority: users below min_pool_size get served first.
    # reserve_pool_size: 0

    # Wait time (milliseconds) before falling back to reserve pool.
    # During this time the coordinator waits for a connection to be returned.
    # reserve_pool_timeout: 3000

    # Minimum connections per user protected from coordinator eviction.
    # Unlike min_pool_size (which triggers prewarm/replenish), this only
    # affects eviction: the coordinator will never evict a user's connections
    # below this number. Does not create connections proactively.
    # Useful when min_pool_size = 0 for most users (no prewarm desired)
    # but you still want eviction fairness under max_db_connections pressure.
    # min_guaranteed_pool_size: 0

    # Patroni REST API endpoints. When the local backend becomes
    # unreachable, pg_doorman queries /cluster to find a live fallback host.
    # patroni_api_urls: []

    # How long the local backend stays marked as down after a failed connect.
    # fallback_cooldown: "30s"

    # HTTP timeout for Patroni API requests.
    # patroni_api_timeout: "5s"

    # TCP connect timeout for fallback candidates.
    # fallback_connect_timeout: "5s"

    # Lifetime of fallback connections; defaults to fallback_cooldown.
    # fallback_lifetime: "30s"

    # --------------------------------------------------------------------------
    # Application Settings
    # --------------------------------------------------------------------------

    # Application name sent to PostgreSQL when opening connections.
    # Useful when sync_server_parameters is disabled.
    # application_name: "my_application"

    # Log SET commands from clients.
    # Default: false
    log_client_parameter_status_changes: false

    # --------------------------------------------------------------------------
    # Users Configuration
    # --------------------------------------------------------------------------
    # Array of users allowed to connect to this pool.
    # Each user must have a unique username within the pool.
    users:
        # Username for client authentication.
      - username: "app_user"

      # Password hash or JWT key path for client authentication.
      # Formats:
      # - MD5: "md5" + md5(password + username)
      # - SCRAM-SHA-256: "SCRAM-SHA-256$iterations:salt$StoredKey:ServerKey"
      # - JWT public key: "jwt-pkey-fpath:/path/to/public.pem"
      #
      # Generate MD5: echo -n "passwordusername" | md5sum
      # Copy from PostgreSQL: SELECT usename, passwd FROM pg_shadow;
        password: "md5dd9a0f26a4302744db881776a09bbfad"

      # Max backend connections to PostgreSQL for this user.
      # Similar to PgBouncer's default_pool_size but set per-user.
      # Default: 40
        pool_size: 40

      # Minimum connections to maintain in the pool.
      # Prewarmed at startup, then maintained by retain cycle.
      # Must be <= pool_size.
        # min_pool_size: 5

      # Override pool-level pool_mode for this user.
        # pool_mode: "session"

      # Override pool-level server_lifetime for this user (in milliseconds).
        # server_lifetime: 600000

      # Server-side credentials for connecting to PostgreSQL.
      #
      # By default pg_doorman uses passthrough authentication: the client's
      # cryptographic proof (MD5 hash or SCRAM ClientKey) is reused to
      # authenticate to the backend automatically. This is the recommended
      # mode — no plaintext passwords in config needed.
      #
      # Set server_username/server_password only when the backend PostgreSQL
      # user differs from the pool username (e.g., username mapping or JWT auth).
        # server_username: "actual_pg_user"
        # server_password: "actual_pg_password"

      # PAM service name for PAM authentication (requires 'pam' feature).
        # auth_pam_service: "pg_doorman"

    # --------------------------------------------------------------------------
    # Dynamic Authentication (auth_query)
    # --------------------------------------------------------------------------

    # Dynamic user authentication via PostgreSQL queries.
    # Instead of listing users statically, pg_doorman fetches credentials from
    # a PostgreSQL database at connection time.

    # Two modes are available:
    # - Dedicated mode (server_user is set): all dynamic users share one pool
    # - Passthrough mode (server_user is not set): each user gets their own pool

    # Static users (defined in 'users') are checked first; auth_query is only used when the username is not found among static users.

    # WARNING: Do not use a superuser for auth queries. Create a SECURITY DEFINER function and a dedicated role (see reference docs).

    # Dedicated mode example (simplest — all dynamic users share one backend connection pool):
    # auth_query:
    #   query: "SELECT passwd FROM pg_shadow WHERE usename = $1"
    #   user: "doorman_auth"
    #   password: "auth_password"
    #   database: "postgres"
    #   workers: 2
    #   server_user: "app"
    #   server_password: "secret"
    #   pool_size: 40
    #   min_pool_size: 0
    #   cache_ttl: "1h"
    #   cache_failure_ttl: "30s"
    #   min_interval: "1s"

    # Passthrough mode example (each dynamic user gets their own backend connection pool):
    # auth_query:
    #   query: "SELECT passwd FROM pg_shadow WHERE usename = $1"
    #   user: "doorman_auth"
    #   password: "auth_password"

    # --------------------------------------------------------------------------
    # Additional Pool Examples
    # --------------------------------------------------------------------------

  # Example: Pool with multiple users
  # multi_user_db:
  #   server_host: "192.168.1.100"
  #   server_port: 5432
  #   pool_mode: "transaction"
  #   users:
  #     - username: "readonly_user"
  #       password: "md5..."
  #       pool_size: 20
  #     - username: "readwrite_user"
  #       password: "SCRAM-SHA-256$..."
  #       pool_size: 10

  # Example: Pool with unix socket connection
  # local_db:
  #   server_host: "/var/run/postgresql"
  #   server_port: 5432
  #   pool_mode: "session"
  #   users:
  #     - username: "local_user"
  #       password: "md5..."
  #       pool_size: 50

  # Example: Pool with JWT authentication
  # jwt_auth_db:
  #   server_host: "127.0.0.1"
  #   server_port: 5432
  #   pool_mode: "transaction"
  #   users:
  #     - username: "jwt_user"
  #       password: "jwt-pkey-fpath:/etc/pg_doorman/jwt/public.pem"
  #       pool_size: 30
  #       server_username: "actual_db_user"
  #       server_password: "actual_password"

  # Example: Pool with server-side credentials mapping
  # mapped_db:
  #   server_host: "db.example.com"
  #   server_port: 5432
  #   server_database: "production"
  #   pool_mode: "transaction"
  #   users:
  #     - username: "app_user"
  #       password: "md5..."
  #       pool_size: 40
  #       server_username: "pg_app_user"
  #       server_password: "secure_password"