Pgbouncer

`services.pgbouncer.adminUsers`

Comma-separated list of database users that are allowed to connect and run all commands on the console. Ignored when authType is any, in which case any user name is allowed in as admin.

Type: null or strings concatenated with ","

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.authDbname`

Database name in the [database] section to be used for authentication purposes. This option can be either global or overriden in the connection string if this parameter is specified.

Type: null or string

Default

null

Example

"authdb"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.authFile`

The name of the file to load user names and passwords from.

See section Authentication file format details: https://www.pgbouncer.org/config.html#authentication-file-format

Most authentication types require that either authFile or authUser be set; otherwise there would be no users defined.

Type: null or path

Default

null

Example

"/secrets/pgbouncer_authfile"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.authHbaFile`

HBA configuration file to use when authType is hba.

See HBA file format details: https://www.pgbouncer.org/config.html#hba-file-format

Type: null or path

Default

null

Example

"/secrets/pgbouncer_hba"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.authQuery`

Query to load user's password from database.

Direct access to pg_shadow requires admin rights. It's preferable to use a non-superuser that calls a SECURITY DEFINER function instead.

Note that the query is run inside the target database. So if a function is used, it needs to be installed into each database.

Type: null or string

Default

null

Example

"SELECT usename, passwd FROM pg_shadow WHERE usename=$1"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.authType`

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. scram-sha-256 Use password check with SCRAM-SHA-256. authFile has to contain SCRAM secrets or plain-text passwords. plain The clear-text password is sent over the wire. Deprecated. trust No authentication is done. The user name must still exist in authFile. any Like the trust method, but the user name given is ignored. Requires that all databases are configured to log in as a specific user. Additionally, the console database allows any user to log in as admin. hba The actual authentication type is loaded from authHbaFile. This allows different authentication methods for different access paths, for example: connections over Unix socket use the peer auth method, connections over TCP must use TLS. pam PAM is used to authenticate users, authFile is ignored. This method is not compatible with databases using the authUser option. The service name reported to PAM is “pgbouncer”. pam is not supported in the HBA configuration file.

Type: one of "cert", "md5", "scram-sha-256", "plain", "trust", "any", "hba", "pam"

Default

"md5"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.authUser`

If authUser is set, then any user not specified in authFile will be queried through the authQuery query from pg_shadow in the database, using authUser. The password of authUser will be taken from authFile. (If the authUser does not require a password then it does not need to be defined in authFile.)

Direct access to pg_shadow requires admin rights. It's preferable to use a non-superuser that calls a SECURITY DEFINER function instead.

Type: null or string

Default

null

Example

"pgbouncer"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.databases`

Detailed information about PostgreSQL database definitions: https://www.pgbouncer.org/config.html#section-databases

Type: attribute set of string

Default

{ }

Example

{bardb = "host=localhost dbname=bazdb";exampledb = "host=/run/postgresql/ port=5432 auth_user=exampleuser dbname=exampledb sslmode=require";foodb = "host=host1.example.com port=5432";}

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.defaultPoolSize`

How many server connections to allow per user/database pair. Can be overridden in the per-database configuration.

Type: signed integer

Default

20

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.enable`

Whether to enable PostgreSQL connection pooler. Type: boolean

Default

false

Example

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.extraConfig`

Any additional text to be appended to config.ini https://www.pgbouncer.org/config.html.

Type: strings concatenated with "\n"

Default

""

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.group`

The group pgbouncer is run as.

Type: string

Default

"pgbouncer"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.homeDir`

Specifies the home directory.

Type: path

Default

"/var/lib/pgbouncer"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.ignoreStartupParameters`

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

Type: null or strings concatenated with ","

Default

null

Example

"extra_float_digits"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.listenAddress`

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.

Type: null or strings concatenated with ","

Default

null

Example

"*"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.listenPort`

Which port to listen on. Applies to both TCP and Unix sockets.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default

6432

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.logFile`

Specifies a log file in addition to journald.

Type: null or string

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.maxClientConn`

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.

Type: signed integer

Default

100

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.maxDbConnections`

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

Type: signed integer

Default

0

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.maxUserConnections`

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

Type: signed integer

Default

0

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.openFilesLimit`

Maximum number of open files.

Type: signed integer

Default

65536

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.openFirewall`

Whether to automatically open the specified TCP port in the firewall.

Type: boolean

Default

false

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.package`

The pgbouncer package to use. Type: package

Default

pkgs.pgbouncer

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.peers`

Optional.

Detailed information about PostgreSQL database definitions: https://www.pgbouncer.org/config.html#section-peers

Type: attribute set of string

Default

{ }

Example

{"1" = "host=host1.example.com";"2" = "host=/tmp/pgbouncer-2 port=5555";}

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.poolMode`

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.

Type: one of "session", "transaction", "statement"

Default

"session"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.statsUsers`

Comma-separated list of database users that are allowed to connect and run read-only queries on the console. That means all SHOW commands except SHOW FDS.

Type: null or strings concatenated with ","

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.syslog`

https://www.pgbouncer.org/config.html#log-settings

Type: null or (submodule)

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.syslog.enable`

Toggles syslog on/off.

Type: boolean

Default

false

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.syslog.syslogFacility`

Under what facility to send logs to syslog.

Type: one of "auth", "authpriv", "daemon", "user", "local0", "local1", "local2", "local3", "local4", "local5", "local6", "local7"

Default

"daemon"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.syslog.syslogIdent`

Under what name to send logs to syslog.

Type: string

Default

"pgbouncer"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.client`

https://www.pgbouncer.org/config.html#tls-settings

Type: null or (submodule)

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.client.caFile`

Path to root certificate file to validate client certificates Type: path

Example

"/secrets/pgbouncer.crt"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.client.certFile`

Path to certificate for private key. Clients can validate it Type: path

Example

"/secrets/pgbouncer.key"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.client.keyFile`

Path to private key for PgBouncer to accept client connections Type: path

Example

"/secrets/pgbouncer.crt"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.client.sslmode`

TLS mode to use for connections from clients. TLS connections are disabled by default.

When enabled, tls.client.keyFile and tls.client.certFile must be also configured to set up the key and certificate PgBouncer uses to accept client connections.

disable Plain TCP. If client requests TLS, it's ignored. Default. allow If client requests TLS, it is used. If not, plain TCP is used. If the client presents a client certificate, it is not validated. prefer Same as allow. require Client must use TLS. If not, the client connection is rejected. If the client presents a client certificate, it is not validated. verify-ca Client must use TLS with valid client certificate. verify-full Same as verify-ca

Type: one of "disable", "allow", "prefer", "require", "verify-ca", "verify-full"

Default

"disable"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.server`

https://www.pgbouncer.org/config.html#tls-settings

Type: null or (submodule)

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.server.caFile`

Root certificate file to validate PostgreSQL server certificates. Type: path

Example

"/secrets/pgbouncer_server.crt"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.server.certFile`

Certificate for private key. PostgreSQL server can validate it. Type: path

Example

"/secrets/pgbouncer_server.key"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.server.keyFile`

Private key for PgBouncer to authenticate against PostgreSQL server. Type: path

Example

"/secrets/pgbouncer_server.crt"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.tls.server.sslmode`

TLS mode to use for connections to PostgreSQL servers. TLS connections are disabled by default.

disable Plain TCP. TLS is not even requested from the server. Default. allow FIXME: if server rejects plain, try TLS? prefer TLS connection is always requested first from PostgreSQL. If refused, the connection will be established over plain TCP. Server certificate is not validated. require Connection must go over TLS. If server rejects it, plain TCP is not attempted. Server certificate is not validated. verify-ca Connection must go over TLS and server certificate must be valid according to tls.server.caFile. Server host name is not checked against certificate. verify-full Connection must go over TLS and server certificate must be valid according to tls.server.caFile. Server host name must match certificate information.

Type: one of "disable", "allow", "prefer", "require", "verify-ca", "verify-full"

Default

"disable"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.user`

The user pgbouncer is run as.

Type: string

Default

"pgbouncer"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.users`

Optional.

Detailed information about PostgreSQL user definitions: https://www.pgbouncer.org/config.html#section-users

Type: attribute set of string

Default

{ }

Example

{user1 = "pool_mode=session";}

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix

`services.pgbouncer.verbose`

Increase verbosity. Mirrors the “-v” switch on the command line.

Type: signed integer

Default

0

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/databases/pgbouncer.nix