Initializer

init(url:)

Create a SQLPostgresConfiguration from a properly formatted URL.

init(url: URL) throws

Discussion

The supported URL formats are:

postgres://username:password@hostname:port/database?tlsmode=mode
postgres+tcp://username:password@hostname:port/database?tlsmode=mode
postgres+uds://username:password@localhost/path?tlsmode=mode#database

The postgres+tcp scheme requests a connection over TCP. The postgres scheme is an alias for postgres+tcp. Only the hostname and username components are required.

The postgres+uds scheme requests a connection via a UNIX domain socket. The username and path components are required. The authority must always be empty or localhost, and may not specify a port.

The allowed mode values for tlsmode are:

Value	Behavior
`disable`	Don’t use TLS, even if the server supports it.
`prefer`	Use TLS if possible.
`require`	Enforce TLS support.

If no tlsmode is specified, the default mode is prefer for TCP connections, or disable for UDS connections. If more than one mode is specified, the last one wins. Whenever a TLS connection is made, full certificate verification (both chain of trust and hostname match) is always enforced, regardless of the mode used.

For compatibility with libpq and previous versions of this package, any of “sslmode”, “tls”, or “ssl” may be used instead of “tlsmode”. There are also various aliases for each of the TLS mode names, as follows:

“disable”: “false”
“prefer”: “allow”, “true”
“require”: “verify-ca”, “verify-full”

The aliases always have the same semantics as the “canonical” modes, despite any differences suggested by their names.

Also for compatibility, the URL scheme may also be postgresql or postgresql+uds.

Note

It is possible to emulate libpq’s definitions for prefer (TLS if available with no certificate verification), require (TLS enforced, but also without certificate verification) and verify-ca (TLS enforced with no hostname verification) by manually specifying the TLS configuration instead of using a URL. It is not possible, by design, to emulate libpq‘s allow mode (TLS only if there is no alternative). It is strongly recommended for both security and privacy reasons to always leave full certificate verification enabled whenever possible. See NIOSSL’s TLSConfiguration for additional information and recommendations.