postgleam/config

Connection configuration for PostgreSQL.

Build a config with default() and the builder functions, or parse a connection URL with from_url:

let assert Ok(cfg) =
  config.from_url("postgres://app:secret@db.internal:5432/app?sslmode=verify-full")

Types

AuthMethod

</>

Authentication methods a server may ask for.

pub type AuthMethod {
  AuthNone
  AuthScram
  AuthMd5
  AuthCleartext
}

Constructors

```
AuthNone
```
The server accepts the connection without a password (trust auth).
```
AuthScram
```
SCRAM-SHA-256 (recommended; mutual authentication).
```
AuthMd5
```
MD5 password hash (legacy; vulnerable to replay with a stolen hash).
```
AuthCleartext
```
Cleartext password. Refused on non-TLS connections even when allowed.

ClientCert

</>

A TLS client certificate and its private key, both PEM file paths.

pub type ClientCert {
  ClientCert(certfile: String, keyfile: String)
}

Constructors

ClientCert(certfile: String, keyfile: String)

Config

</>

Connection configuration.

The password is held in an opaque Secret so that printing a config (with echo or string.inspect) does not reveal it.

pub type Config {
  Config(
    host: String,
    port: Int,
    database: String,
    username: String,
    password: Secret,
    timeout: Int,
    connect_timeout: Int,
    extra_parameters: List(#(String, String)),
    ssl: SslMode,
    ssl_ca_file: option.Option(String),
    ssl_client_cert: option.Option(ClientCert),
    allowed_auth: List(AuthMethod),
    pgbouncer: Bool,
    idle_interval: Int,
    queue_timeout: Int,
    max_message_size: Int,
  )
}

Constructors

```
Config(
  host: String,
  port: Int,
  database: String,
  username: String,
  password: Secret,
  timeout: Int,
  connect_timeout: Int,
  extra_parameters: List(#(String, String)),
  ssl: SslMode,
  ssl_ca_file: option.Option(String),
  ssl_client_cert: option.Option(ClientCert),
  allowed_auth: List(AuthMethod),
  pgbouncer: Bool,
  idle_interval: Int,
  queue_timeout: Int,
  max_message_size: Int,
)
```
Arguments

timeout

Milliseconds to wait for each response from the server. A query that exceeds it is cancelled on the server and returns TimeoutError.

connect_timeout

Milliseconds to wait for the TCP connection and TLS handshake.

ssl_ca_file

PEM file with the CA certificates used to verify the server (SslVerified only). None uses the operating system’s trust store.

ssl_client_cert

PEM certificate and key files for TLS client certificate auth.

allowed_auth

Authentication methods the client will agree to use.

idle_interval

Pool only: idle connections are pinged after this many milliseconds.

queue_timeout

Pool only: how long a caller waits for a free connection.

max_message_size

Largest single protocol message accepted from the server, in bytes.

Secret

opaque </>

A secret string (a password). string.inspect shows only //fn() { ... }.

pub opaque type Secret

SslMode

</>

SSL connection mode.

pub type SslMode {
  SslDisabled
  SslVerified
  SslUnverified
}

Constructors

```
SslDisabled
```
No TLS (plain TCP). Only for local development.
```
SslVerified
```
TLS required; the server certificate and host name are verified.
```
SslUnverified
```
TLS required, but the certificate is NOT verified. Protects against passive sniffing only; an active attacker can impersonate the server.

UrlError

</>

Errors from from_url.

pub type UrlError {
  InvalidUrl
  UnsupportedScheme(String)
  InvalidSslMode(String)
  InvalidConnectTimeout(String)
}

Constructors

```
InvalidUrl
```
```
UnsupportedScheme(String)
```
```
InvalidSslMode(String)
```
```
InvalidConnectTimeout(String)
```

Values

allowed_auth

</>

pub fn allowed_auth(
  config: Config,
  methods: List(AuthMethod),
) -> Config

Restrict which authentication methods the client will use, like libpq’s require_auth. For example [AuthScram] refuses MD5, cleartext and passwordless servers.

default

</>

pub fn default() -> Config

Default config for a local server: postgres@localhost:5432/postgres, no password, no TLS. Set a password with password.

extra_parameters

</>

pub fn extra_parameters(
  config: Config,
  params: List(#(String, String)),
) -> Config

Set extra startup parameters sent to PostgreSQL (e.g. application_name).

from_url

</>

pub fn from_url(url: String) -> Result(Config, UrlError)

Parse a connection URL such as postgres://user:password@host:5432/database?sslmode=verify-full.

Supported query parameters: sslmode (disable, require, verify-ca, verify-full), sslrootcert, connect_timeout (seconds) and application_name. Unknown parameters are sent to the server as startup parameters.

host

</>

pub fn host(config: Config, host: String) -> Config

Set the server host name or IP address.

idle_interval

</>

pub fn idle_interval(config: Config, ms: Int) -> Config

Set the idle ping interval in milliseconds (pool only). Connections idle for longer than this are pinged. Default: 1000ms.

max_message_size

</>

pub fn max_message_size(config: Config, bytes: Int) -> Config

Set the largest protocol message accepted from the server. Default 1 GiB.

password

</>

pub fn password(config: Config, password: String) -> Config

Set the password.

pgbouncer

</>

pub fn pgbouncer(config: Config, enabled: Bool) -> Config

Enable PgBouncer compatibility mode. Uses unnamed prepared statements with Flush to avoid mid-query backend reassignment in PgBouncer transaction pooling mode.

port

</>

pub fn port(config: Config, port: Int) -> Config

Set the server port.

queue_timeout

</>

pub fn queue_timeout(config: Config, ms: Int) -> Config

Set the maximum time in milliseconds to wait for a pool connection. If no connection becomes available within this time, returns TimeoutError. Default: 5000ms.

reveal

</>

pub fn reveal(secret: Secret) -> String

Read the value of a secret.

secret

</>

pub fn secret(value: String) -> Secret

Wrap a string as a secret.

ssl

</>

pub fn ssl(config: Config, mode: SslMode) -> Config

Set the TLS mode.

ssl_ca_file

</>

pub fn ssl_ca_file(config: Config, path: String) -> Config

Verify the server against the CA certificates in this PEM file instead of the system trust store (for RDS, Cloud SQL or a private CA).

ssl_client_cert

</>

pub fn ssl_client_cert(
  config: Config,
  certfile certfile: String,
  keyfile keyfile: String,
) -> Config

Authenticate with a TLS client certificate (PEM certificate and key files).

timeout

</>

pub fn timeout(config: Config, timeout: Int) -> Config

Set the per-response timeout in milliseconds.

username

</>

pub fn username(config: Config, username: String) -> Config

Set the user name.

validate

</>

pub fn validate(config: Config) -> Result(Config, String)

Check a config for values that can never work. Called by connect.

Constructors

Constructors

Constructors

Arguments

Constructors

Constructors