- 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. - 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_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_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.
- 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. - 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)