ConnectionConfiguration

ConnectionConfiguration is the primary connection configuration type accepted by Connection, Pool and getConnectionConfig(). It extends DatabaseConnectionParams and SocketOptions, adding a buffer option of its own.

interface ConnectionConfiguration extends DatabaseConnectionParams, SocketOptions {
  buffer?: SmartBufferConfig;
}

Key	Type	Default	Description
buffer	SmartBufferConfig		Configures the internal socket read buffer (pageSize, maxLength, houseKeepInterval)

DatabaseConnectionParams

The connection/authentication/session portion of the configuration.

Key	Type	Default	Description
host	string		Server hostname or, prefixed with /, a Unix domain socket path
port	number		Server port
user	string		Database user
password	string | (() => string | Promise<string>)		Password, or a function (sync or async) that resolves to one — useful for a token that is fetched or refreshed on demand
database	string		Database name
applicationName	string		Value reported to the server as application_name
replication	'database' | 'true'		Opens the connection in replication mode, which is what lets it run START_REPLICATION. Set by LogicalReplication; a connection in this mode cannot serve ordinary queries once streaming has begun
hosts	{ host: string; port?: number }[]		Additional servers to try, in order, when the first one cannot be used. Also accepted as a comma-separated host, or in a connection string (postgres://a:5432,b:5433/db). Each entry falls back to the top-level port when it does not carry one of its own. Selection happens when a connection is opened, so a cluster that has failed over to another node is found on the next connect — a query already in flight when a server goes down still fails
targetSessionAttrs	'read-write' | 'read-only' | 'primary' | 'standby' | 'prefer-standby'		Which server in hosts is acceptable, mirroring libpq's option of the same name. A server that does not match is dropped and the next one tried, which is how read-write finds the current primary
sslNegotiation	'postgres' | 'direct'	'postgres'	How TLS is started: postgres asks first with an SSLRequest and waits for the server's yes or no; direct begins the TLS handshake straight away, announcing the postgresql protocol over ALPN. direct saves a round trip and leaves no plaintext preamble, but needs PostgreSQL 17+ and ssl set — an older server just closes the connection
channelBinding	'prefer' | 'require' | 'disable'	'prefer'	Whether SCRAM authentication binds itself to the TLS channel, mirroring libpq's option of the same name. prefer uses it when the server offers it, require refuses to connect otherwise, disable never asks for it. Binding is what protects the login when the certificate itself is not verified, which is the usual case with sslmode=require or a self-signed certificate
requireSSL	boolean		Requires the connection to be encrypted
ssl	tls.ConnectionOptions		Node.js TLS options passed through when negotiating SSL
timezone	string		Session timezone
schema	string		Default schema (search_path)
connectTimeoutMs	number		Connection timeout in milliseconds
autoCommit	boolean	false*	Specifies whether to execute queries in auto-commit mode. *Only setting it explicitly to false has an effect — it then makes the first statement outside an explicit transaction open one implicitly, which stays open until you commit()/rollback() or pass autoCommit: true on a later call. Leaving it unset behaves the same as true: every statement commits on its own, as in psql. Can be overridden per call via QueryOptions.autoCommit (default true there)
rollbackOnError	boolean	true	When off, if a statement in a transaction block generates an error, the error is ignored and the transaction continues. When on (the default), a statement in a transaction block that generates an error aborts the entire transaction
asyncErrorHandling	boolean	true	Whether a thrown error's stack trace points at the application code that called query()/execute() (etc.) across the await, instead of an internal async frame inside the library. Getting this right costs a measurable amount of CPU when many calls are in flight at once (e.g. pipelined queries) — set to false to skip it
debugLogger	DebugLogger		(namespace: string, format: any, ...args: any[]) => void callback used for internal debug logging

SocketOptions

Key	Type	Default	Description
keepAlive	boolean		Enables TCP keep-alive on the socket

note

rollbackOnError and asyncErrorHandling set here become the connection-wide defaults; both may be overridden per call via QueryOptions / ScriptExecuteOptions.