> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# PostgreSQL Configuration

Status: Unstable.

Every field of the configuration that registers a PostgreSQL database as an export destination, a provider of kind `adbc-postgres`, from its JSON schema. To learn how to register one and how its secrets reach the worker, see [Destinations](/managing-amp/pipelines/destinations).

## Example

A provider named `warehouse`, whose alias is `WAREHOUSE`:

```toml
kind = "adbc-postgres"
host = "${AMP_ADBC_WAREHOUSE_HOST}"
port = { default = true }
database = "${AMP_ADBC_WAREHOUSE_DATABASE}"
username = "${AMP_ADBC_WAREHOUSE_USERNAME}"
password = "${AMP_ADBC_WAREHOUSE_PASSWORD}"
ssl_mode = "${AMP_ADBC_WAREHOUSE_SSL_MODE}"
ssl_cert = { default = true }
ssl_key = { default = true }
ssl_root_cert = { default = true }
ssl_crl = { default = true }
data_schema = "analytics"
application_name = "amp_exporter"
timeout_secs = 30
pool = { max_connections = 8 }
export_state_mode = "upsert"
```

## Provider

### `kind`

The provider kind, must be `"adbc-postgres"`.

* **Type**: string
* **Required**

```toml
kind = "adbc-postgres"
```

### `alias`

The provider's alias, which names its environment variables: `AMP_ADBC_<ALIAS>_<FIELD>`. Amp derives it from the provider's name, in uppercase, so leave it out: a provider named `warehouse` has the alias `WAREHOUSE`. If you set it, set it to that alias: registration fails with `ADBC_ALIAS_MISMATCH` otherwise.

* **Type**: string
* **Allowed**: at most 32 characters
* **Default**: the provider's name, in uppercase

```toml
alias = "WAREHOUSE"
```

## Connection

Each of these fields is a secret: give it as a reference to its environment variable, which the worker resolves when it connects, or as a decoration table. A plain value is rejected.

A decoration table sets how the value resolves:

* `{ default = true }` uses the field's default when the variable isn't set.
* `{ required = false }` leaves the field unset when the variable isn't set.
* `{ using = "OTHER" }` reads the variable of the provider whose alias is `OTHER`, as in `AMP_ADBC_OTHER_HOST`, to share credentials between providers. `{ using = { alias = "OTHER", version = "^1" } }` also requires that provider's version to match.

### `host`

The destination server's host: a DNS name (dotted FQDNs like `db.internal.example.com` included), `localhost`, or an IPv4 literal.

The environment variable's value must be hostname-shaped: ASCII letters and digits plus `.`, `-`, `_`, starting with a letter, digit, or underscore, at most 253 bytes. IPv6 literals need bracket-and-colon syntax and are not supported.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_HOST`
* **Default**, with `{ default = true }`: `localhost`

```toml
host = "${AMP_ADBC_WAREHOUSE_HOST}"
```

### `port`

The destination server's TCP port.

The environment variable's value must be an integer in 0-65535 (environment values are strings, so a numeric string).

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_PORT`
* **Default**, with `{ default = true }`: `5433`

```toml
port = "${AMP_ADBC_WAREHOUSE_PORT}"
```

### `database`

The destination database name, embedded in the connection URI.

The environment variable's value must be at most 63 bytes, start with an ASCII letter or underscore, and contain no `-`, `.`, `~`, `$`, or quote characters.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_DATABASE`
* **Default**, with `{ default = true }`: `postgres`

```toml
database = "${AMP_ADBC_WAREHOUSE_DATABASE}"
```

### `username`

The connection role (username), embedded in the connection URI.

The environment variable's value must be at most 63 bytes, start with an ASCII letter or underscore, and contain no `-`, `.`, `~`, `$`, or quote characters.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_USERNAME`
* **Default**, with `{ default = true }`: `admin`

```toml
username = "${AMP_ADBC_WAREHOUSE_USERNAME}"
```

### `password`

The connection password.

The environment variable's value may be any string; URI delimiters are percent-encoded before embedding, so they cannot break the connection URI. Trust/peer authentication setups declare `{ default = true }` and never set the variable.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_PASSWORD`
* **Default**, with `{ default = true }`: the empty string

```toml
password = "${AMP_ADBC_WAREHOUSE_PASSWORD}"
```

### `ssl_mode`

The libpq `sslmode` connection-security level; `prefer` attempts SSL but falls back to plaintext.

The environment variable's value must be one of `disable`, `allow`, `prefer`, `require`, `verify_ca`, or `verify_full` (snake_case; the hyphenated libpq spellings `verify-ca` and `verify-full` are produced on the wire).

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_SSL_MODE`
* **Default**, with `{ default = true }`: `prefer`

```toml
ssl_mode = "${AMP_ADBC_WAREHOUSE_SSL_MODE}"
```

### `ssl_cert`

Client certificate path (libpq `sslcert`).

The environment variable's value must be a non-empty local filesystem path (e.g. `/etc/ssl/client.crt`) with no parent-directory (`..`) components; absolute paths are accepted.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_SSL_CERT`
* **Default**, with `{ default = true }`: unset

```toml
ssl_cert = "${AMP_ADBC_WAREHOUSE_SSL_CERT}"
```

### `ssl_key`

Client private-key path (libpq `sslkey`).

The environment variable's value must be a non-empty local filesystem path (e.g. `/etc/ssl/client.key`) with no parent-directory (`..`) components; absolute paths are accepted.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_SSL_KEY`
* **Default**, with `{ default = true }`: unset

```toml
ssl_key = "${AMP_ADBC_WAREHOUSE_SSL_KEY}"
```

### `ssl_root_cert`

Root CA certificate path (libpq `sslrootcert`).

The environment variable's value must be a non-empty local filesystem path (e.g. `/etc/ssl/root.crt`) with no parent-directory (`..`) components; absolute paths are accepted.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_SSL_ROOT_CERT`
* **Default**, with `{ default = true }`: unset

```toml
ssl_root_cert = "${AMP_ADBC_WAREHOUSE_SSL_ROOT_CERT}"
```

### `ssl_crl`

Certificate revocation list path (libpq `sslcrl`).

The environment variable's value must be a non-empty local filesystem path (e.g. `/etc/ssl/revoked.crl`) with no parent-directory (`..`) components; absolute paths are accepted.

* **Type**: environment variable reference or decoration table
* **Required**
* **Environment variable**: `AMP_ADBC_<ALIAS>_SSL_CRL`
* **Default**, with `{ default = true }`: unset

```toml
ssl_crl = "${AMP_ADBC_WAREHOUSE_SSL_CRL}"
```

## Export settings

### `data_schema`

The destination schema receiving the exported data tables. It isn't a secret, so give it as a plain value. Defaults to `public`.

A PostgreSQL identifier: at most 63 bytes, starting with an ASCII letter or underscore, with no `-`, `.`, `~`, or `$` characters. A SQL keyword is accepted and stored double-quoted.

* **Type**: string
* **Allowed**: at most 63 characters
* **Default**: `"public"`

```toml
data_schema = "public"
```

### `application_name`

Optional `application_name` reported to the server, shown in `pg_stat_activity` and server log lines. Percent-encoded into the connection URI; when omitted, no `application_name` parameter is sent.

A PostgreSQL identifier: at most 63 bytes, starting with an ASCII letter or underscore, with no `-`, `.`, `~`, or `$` characters. A SQL keyword is accepted and stored double-quoted.

* **Type**: string
* **Allowed**: at most 63 characters
* **Default**: none

```toml
application_name = "amp_worker"
```

### `timeout_secs`

The per-operation timeout applied to connection and statement calls, in whole seconds, defaulting to 30.

Zero is rejected: engines commonly treat a zero timeout as "wait forever" (libpq's `connect_timeout=0`, for one), which would hang a worker on an unreachable destination instead of failing it.

* **Type**: integer
* **Allowed**: at least 1
* **Default**: `30`

```toml
timeout_secs = 30
```

### `pool`

Connection-pool sizing and patience applied to one export target, configured as the `[pool]` table of its provider config.

One provider serves many concurrent export jobs, each holding an exclusive connection for its whole transactional lifecycle; these knobs bound that fan-out per target. Both fields (and the table itself) default when omitted.

* **Type**: table
* **Default**: each field's default

### `pool.max_connections`

Maximum concurrently checked-out connections, defaulting to 4. The default is conservative against a destination's own connection budget. Zero is rejected.

* **Type**: integer
* **Allowed**: at least 1
* **Default**: `4`

```toml
[pool]
max_connections = 4
```

### `pool.acquire_timeout_secs`

How long a checkout waits for a free connection slot before failing, in whole seconds, defaulting to 30. Zero is rejected.

* **Type**: integer
* **Allowed**: at least 1
* **Default**: `30`

```toml
[pool]
acquire_timeout_secs = 30
```

### `export_state_mode`

How the destination `amp_export_state` table records each materialization event.

Fixed per provider over its lifetime: a mid-life switch would leave the state table in a shape the new mode's SQL can't read.

* **Type**: string
* **Default**: `"upsert"`

What each value does:

* `upsert`: One row per `(target_schema, target_table)`; each event overwrites it in place. Compact, no audit trail.
* `append`: Append-only audit trail: one new `commit_id`-keyed row per event. At-least-once, so a retried microbatch appends a duplicate row; use `upsert_retry` to dedupe in place.
* `upsert_retry`: `append`'s table shape, but the same transaction deletes prior rows for the same logical event. DDL is identical to `append`, so switching between the two needs no migration.

```toml
export_state_mode = "upsert"
```

### `state_schema`

The schema holding the `amp_export_state` bookkeeping table, kept apart from the exported data tables. It isn't a secret, so give it as a plain value. Defaults to `amp`.

A PostgreSQL identifier: at most 63 bytes, starting with an ASCII letter or underscore, with no `-`, `.`, `~`, or `$` characters. A SQL keyword is accepted and stored double-quoted.

* **Type**: string
* **Allowed**: at most 63 characters
* **Default**: `"amp"`

```toml
state_schema = "amp"
```