path: root/nixos/modules/services/databases/pgbouncer.nix

{ lib, pkgs, config, ... } :

with lib;

let
  cfg = config.services.pgbouncer;

  confFile = pkgs.writeTextFile {
    name = "pgbouncer.ini";
    text =  ''
      [databases]
      ${concatStringsSep "\n"
      (mapAttrsToList (dbname : settings : "${dbname} = ${settings}") cfg.databases)}

      [users]
      ${concatStringsSep "\n"
      (mapAttrsToList (username : settings : "${username} = ${settings}") cfg.users)}

      [peers]
      ${concatStringsSep "\n"
      (mapAttrsToList (peerid : settings : "${peerid} = ${settings}") cfg.peers)}

      [pgbouncer]
      # general
      ${optionalString (cfg.ignoreStartupParameters != null) "ignore_startup_parameters = ${cfg.ignoreStartupParameters}"}
      listen_port = ${toString cfg.listenPort}
      ${optionalString (cfg.listenAddress != null) "listen_addr = ${cfg.listenAddress}"}
      pool_mode = ${cfg.poolMode}
      max_client_conn = ${toString cfg.maxClientConn}
      default_pool_size = ${toString cfg.defaultPoolSize}
      max_user_connections = ${toString cfg.maxUserConnections}
      max_db_connections = ${toString cfg.maxDbConnections}

      #auth
      auth_type = ${cfg.authType}
      ${optionalString (cfg.authHbaFile != null) "auth_hba_file = ${cfg.authHbaFile}"}
      ${optionalString (cfg.authFile != null) "auth_file = ${cfg.authFile}"}
      ${optionalString (cfg.authUser != null) "auth_user = ${cfg.authUser}"}
      ${optionalString (cfg.authQuery != null) "auth_query = ${cfg.authQuery}"}
      ${optionalString (cfg.authDbname != null) "auth_dbname = ${cfg.authDbname}"}

      # TLS
      ${optionalString (cfg.tls.client != null) ''
      client_tls_sslmode = ${cfg.tls.client.sslmode}
      client_tls_key_file = ${cfg.tls.client.keyFile}
      client_tls_cert_file = ${cfg.tls.client.certFile}
      client_tls_ca_file = ${cfg.tls.client.caFile}
      ''}
      ${optionalString (cfg.tls.server != null) ''
      server_tls_sslmode = ${cfg.tls.server.sslmode}
      server_tls_key_file = ${cfg.tls.server.keyFile}
      server_tls_cert_file = ${cfg.tls.server.certFile}
      server_tls_ca_file = ${cfg.tls.server.caFile}
      ''}

      # log
      ${optionalString (cfg.logFile != null) "logfile = ${cfg.homeDir}/${cfg.logFile}"}
      ${optionalString (cfg.syslog != null) ''
      syslog = ${if cfg.syslog.enable then "1" else "0"}
      syslog_ident = ${cfg.syslog.syslogIdent}
      syslog_facility = ${cfg.syslog.syslogFacility}
      ''}
      ${optionalString (cfg.verbose != null) "verbose = ${toString cfg.verbose}"}

      # console access
      ${optionalString (cfg.adminUsers != null) "admin_users = ${cfg.adminUsers}"}
      ${optionalString (cfg.statsUsers != null) "stats_users = ${cfg.statsUsers}"}

      # linux
      pidfile = /run/pgbouncer/pgbouncer.pid

      # extra
      ${cfg.extraConfig}
    '';
  };

in {

  options.services.pgbouncer = {

    # NixOS settings

    enable = mkEnableOption (lib.mdDoc "PostgreSQL connection pooler");

    package = mkOption {
      type = types.package;
      default = pkgs.pgbouncer;
      defaultText = literalExpression "pkgs.pgbouncer";
      description = lib.mdDoc ''
        The pgbouncer package to use.
      '';
    };

    openFirewall = mkOption {
      type = types.bool;
      default = false;
      description = lib.mdDoc ''
        Whether to automatically open the specified TCP port in the firewall.
      '';
    };

    # Generic settings

    logFile = mkOption {
      type = types.nullOr types.str;
      default = "pgbouncer.log";
      description = lib.mdDoc ''
        Specifies the log file.
        Either this or syslog has to be specified.
      '';
    };

    listenAddress = mkOption {
      type = types.nullOr types.commas;
      example = "*";
      default = null;
      description = lib.mdDoc ''
        Specifies a list (comma-separated) of addresses where to listen for TCP connections.
        You may also use * meaning “listen on all addresses”.
        When not set, only Unix socket connections are accepted.

        Addresses can be specified numerically (IPv4/IPv6) or by name.
      '';
    };

    listenPort = mkOption {
      type = types.port;
      default = 6432;
      description = lib.mdDoc ''
        Which port to listen on. Applies to both TCP and Unix sockets.
      '';
    };

    poolMode = mkOption {
      type = types.enum [ "session" "transaction" "statement" ];
      default = "session";
      description = lib.mdDoc ''
        Specifies when a server connection can be reused by other clients.

        session
            Server is released back to pool after client disconnects. Default.
        transaction
            Server is released back to pool after transaction finishes.
        statement
            Server is released back to pool after query finishes.
            Transactions spanning multiple statements are disallowed in this mode.
      '';
    };

    maxClientConn = mkOption {
      type = types.int;
      default = 100;
      description = lib.mdDoc ''
        Maximum number of client connections allowed.

        When this setting is increased, then the file descriptor limits in the operating system
        might also have to be increased. Note that the number of file descriptors potentially
        used is more than maxClientConn. If each user connects under its own user name to the server,
        the theoretical maximum used is:
        maxClientConn + (max pool_size * total databases * total users)

        If a database user is specified in the connection string (all users connect under the same user name),
        the theoretical maximum is:
        maxClientConn + (max pool_size * total databases)

        The theoretical maximum should never be reached, unless somebody deliberately crafts a special load for it.
        Still, it means you should set the number of file descriptors to a safely high number.
      '';
    };

    defaultPoolSize = mkOption {
      type = types.int;
      default = 20;
      description = lib.mdDoc ''
        How many server connections to allow per user/database pair.
        Can be overridden in the per-database configuration.
      '';
    };

    maxDbConnections = mkOption {
      type = types.int;
      default = 0;
      description = lib.mdDoc ''
        Do not allow more than this many server connections per database (regardless of user).
        This considers the PgBouncer database that the client has connected to,
        not the PostgreSQL database of the outgoing connection.

        This can also be set per database in the [databases] section.

        Note that when you hit the limit, closing a client connection to one pool will
        not immediately allow a server connection to be established for another pool,
        because the server connection for the first pool is still open.
        Once the server connection closes (due to idle timeout),
        a new server connection will immediately be opened for the waiting pool.

        0 = unlimited
      '';
    };

    maxUserConnections = mkOption {
      type = types.int;
      default = 0;
      description = lib.mdDoc ''
        Do not allow more than this many server connections per user (regardless of database).
        This considers the PgBouncer user that is associated with a pool,
        which is either the user specified for the server connection
        or in absence of that the user the client has connected as.

        This can also be set per user in the [users] section.

        Note that when you hit the limit, closing a client connection to one pool
        will not immediately allow a server connection to be established for another pool,
        because the server connection for the first pool is still open.
        Once the server connection closes (due to idle timeout), a new server connection
        will immediately be opened for the waiting pool.

        0 = unlimited
      '';
    };

    ignoreStartupParameters = mkOption {
      type = types.nullOr types.commas;
      example = "extra_float_digits";
      default = null;
      description = lib.mdDoc ''
        By default, PgBouncer allows only parameters it can keep track of in startup packets:
        client_encoding, datestyle, timezone and standard_conforming_strings.

        All others parameters will raise an error.
        To allow others parameters, they can be specified here, so that PgBouncer knows that
        they are handled by the admin and it can ignore them.

        If you need to specify multiple values, use a comma-separated list.

        IMPORTANT: When using prometheus-pgbouncer-exporter, you need:
        extra_float_digits
        <https://github.com/prometheus-community/pgbouncer_exporter#pgbouncer-configuration>
      '';
    };

    # Section [databases]
    databases = mkOption {
      type = types.attrsOf types.str;
      default = {};
      example = {
        exampledb = "host=/run/postgresql/ port=5432 auth_user=exampleuser dbname=exampledb sslmode=require";
        bardb = "host=localhost dbname=bazdb";
        foodb  = "host=host1.example.com port=5432";
      };
      description = lib.mdDoc ''
        Detailed information about PostgreSQL database definitions:
        <https://www.pgbouncer.org/config.html#section-databases>
      '';
    };

    # Section [users]
    users = mkOption {
      type = types.attrsOf types.str;
      default = {};
      example = {
        user1 = "pool_mode=session";
      };
      description = lib.mdDoc ''
        Optional.

        Detailed information about PostgreSQL user definitions:
        <https://www.pgbouncer.org/config.html#section-users>
      '';
    };

    # Section [peers]
    peers = mkOption {
      type = types.attrsOf types.str;
      default = {};
      example = {
        "1" = "host=host1.example.com";
        "2" = "host=/tmp/pgbouncer-2 port=5555";
      };
      description = lib.mdDoc ''
        Optional.

        Detailed information about PostgreSQL database definitions:
        <https://www.pgbouncer.org/config.html#section-peers>
      '';
    };

    # Authentication settings
    authType = mkOption {
      type = types.enum [ "cert" "md5" "scram-sha-256" "plain" "trust" "any" "hba" "pam" ];
      default = "md5";
      description = lib.mdDoc ''
        How to authenticate users.

        cert
            Client must connect over TLS connection with a valid client certificate.
            The user name is then taken from the CommonName field from the certificate.
        md5
            Use MD5-based password check. This is the default authentication method.
            authFile may contain both MD5-encrypted and plain-text passwords.
            If md5 is configured and a user has a SCRAM secret, then SCRAM authentication is used automatically instead.