Config

Fields

host: := "localhost"

A host name or address, or a directory holding the server's Unix socket (starts with /).

port: u16

hostaddr: string

An address to connect to instead of looking host up. host is still the name the server's certificate is checked against and the password file is searched by.

hosts: [] Host_Port

Every host of a connection string such as host1:5432,host2:5433, the first one included. Empty for one host (host and port). With several, connect tries them in turn until one accepts the login and suits target_session_attrs; host, hostaddr and port are then only the first entry's copy.

target_session_attrs: := Target_Session_Attrs.ANY

load_balance_hosts: := Load_Balance_Hosts.DISABLE

user: string

empty: $USER

password: string

database: string

empty: the user name

application_name: := "jai"

options: string

sent as the options startup parameter: "-c search_path=app"

parameters: [] Startup_Parameter

More startup parameters, or replacements for the client's own (client_encoding, DateStyle, IntervalStyle), matched by name without regard to case. Text-format dates, times and intervals only decode with DateStyle ISO and IntervalStyle postgres.

send_styles: := true

Send DateStyle ISO and IntervalStyle postgres. false leaves both to the server's settings (as psql does); text-format dates, times and intervals may then fail to decode.

on_notice: Notice_Proc

The connection's on_notice and user_data from the start, so notices sent while logging in (a login event trigger's, say) reach them too. Null keeps the default, which logs.

user_data: *void

json_options: Json_Options

How json and jsonb columns decode into Json(T): unknown and missing fields, duplicate keys, depth and size limits. Each result starts with these, and its json_options can be changed before get.

ssl_mode: := Ssl_Mode.PREFER

ssl_direct: := false

Start TLS at once, with ALPN postgresql, instead of asking first (PostgreSQL 17 and later): saves a round trip. Needs ssl_mode REQUIRE or stricter.

ssl_root_cert_pem: string

The roots to trust, as PEM. With ssl_mode VERIFY_CA or VERIFY_FULL, empty means the system's roots. With REQUIRE or PREFER, roots given are checked all the same (the chain, not the name, as libpq does with a root.crt), and empty means no check. The chain must end in a self-signed certificate from this list.

ssl_crl_pem: string

Certificate revocation lists (PEM, any number, or one DER) for the chain: if the server's certificate is listed, or none of them was issued by its issuer, the connection fails.

ssl_cert_pem: string

The client certificate chain (PEM, the client's certificate first) and its private key (PEM or DER), for servers that ask for one. ssl_key_password decrypts an encrypted key. Both ssl_cert_pem and ssl_key are needed to send a certificate; ssl_key_file is only the name error messages use for the key.

ssl_key: string

ssl_key_password: string

ssl_key_file: string

ssl_cert_mode: := Ssl_Cert_Mode.ALLOW

ssl_sni: := true

Send the host name as SNI, unless it is an IP address or a socket directory.

ssl_key_log_file: string

Appends the TLS session's secrets to this file, in the key log format Wireshark reads, for debugging. A file that cannot be opened is reported on stderr; the connection goes on.

ssl_min_protocol_version: := Ssl_Protocol_Version.TLS_1_2

ssl_max_protocol_version: := Ssl_Protocol_Version.TLS_1_3

channel_binding: := Channel_Binding.PREFER

min_protocol_version: := Protocol_Version.V3_0

The protocol versions to use, like libpq's min_protocol_version and max_protocol_version. The startup message asks for the maximum; a server that speaks less answers with the version it does, which the connection uses unless it is below the minimum (then connecting fails). The default is 3.0, as libpq's: .LATEST asks for 3.2, which PostgreSQL 18 and later speak.

max_protocol_version: := Protocol_Version.V3_0

statement_cache: := Statement_Cache_Mode.ON

Named prepared statements, kept per connection for typed queries (Pg.query, execute, ...): the first run of a query parses it, later runs only bind. .OFF uses unnamed statements only, for poolers that do not track named ones (PgBouncer before 1.21). The cache holds statement_cache_size statements; the least recently used is closed to make room.

statement_cache_size: := 256

verify_statements: := false

The first time a connection prepares a statement, ask the server what it returns and fail with an error if its columns are not the ones the query was compiled against, instead of reading the rows wrongly after a migration under a running program. Costs one round trip per statement and connection.

statement_timeout: := 0

The server's statement_timeout for the session, in milliseconds; 0 keeps the server's own. Sent as a startup parameter, so a pooler that rejects unknown parameters needs options=-c statement_timeout=... or a role setting instead.

connect_timeout: := 10_000

The whole connect (TCP, TLS, authentication), in milliseconds; negative: no limit.

cancel_timeout: := 2_000

After a deadline or cancel ends a query: how long to spend asking the server to stop it and reading what is left of its answer, in milliseconds. The connection breaks if that fails.

max_scram_iterations: := 1_000_000

A server could ask for any number of SCRAM iterations to waste the client's time.

allow_cleartext_password: := false

Send the password in clear text when the server asks, without TLS.

passfile: string

The password file to look in when password is empty: lines of host:port:database:user:password, * matching anything, \ escaping : and \. Empty: $PGPASSFILE, then ~/.pgpass. A file others can read is ignored, as in libpq.

require_auth: string

The authentication methods the server may use, as libpq's require_auth: a comma separated list of password, md5, gss, sspi, scram-sha-256 and none, or the same each with a ! in front to forbid them. Empty: any.

owned: bool

set by parse_url: the strings belong to the config (free_config)