The databroker service manages all persistent state within Pomerium. These settings control how the databroker service will store this state.

For more information on the databroker service see [Persistence & Data storage](https://www.pomerium.com/docs/internals/data-storage.md).

## Databroker Storage Type

**Databroker Storage Type** sets the backend storage type:

- `memory` — data is stored in main memory
- `file` — data is stored in a local directory
- `postgres` — data is stored in an external PostgreSQL database

The in-memory option is sufficient for single-replica Pomerium deployments. A PostgreSQL database is required when running multiple replicas of Pomerium, in order to ensure that all replicas share a consistent view of the application state.

For more information see [Persistence & Data storage: Backends](https://www.pomerium.com/docs/internals/data-storage.md#backends).

### How to Configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `databroker_storage_type` | `DATABROKER_STORAGE_TYPE` | `string` | `memory` |

### Examples

```yaml
databroker_storage_type: postgres
```

```bash
DATABROKER_STORAGE_TYPE=postgres
```

**Enterprise:**

`databroker_storage_type` is a bootstrap configuration setting and is not configurable in the Console.

**Zero:**

In Pomerium Zero, the storage type is **automatically inferred** from the connection string format and does not need to be configured separately:

- `file:///path/to/directory` → file backend
- `postgres://...` or `postgresql://...` → Postgres backend
- Empty/unset → in-memory (default)

See [Databroker Storage Connection String](#databroker-storage-connection-string) below for configuration details.

**Kubernetes:**

See Kubernetes [Storage reference](https://www.pomerium.com/docs/deploy/k8s/reference.md#storage) for more information.

## Databroker Storage Connection String

**Databroker Storage Connection String** tells Pomerium which directory to use for the `file` storage type or how to connect to an external PostgreSQL database for the `postgres` storage type. This connection string may be provided directly in the configuration or read from a file.

This setting is **required** when the storage type is set to `postgres`. It is optional but recommended for the `file` storage type to specify the storage directory.

### How to Configure the File Storage Type

The connection string should use the `file://` schema followed by a path to indicate the directory to store files:

**Core:**

```yaml
databroker_storage_connection_string: file:///var/pomerium/databroker
```

```bash
DATABROKER_STORAGE_CONNECTION_STRING=file:///var/pomerium/databroker
```

**Enterprise:**

`databroker_storage_connection_string` is a bootstrap configuration setting and is not configurable in the Console.

**Zero:**

In Pomerium Zero, configure the connection string in the **Settings → General** section of the Zero console. The storage type is automatically inferred from the connection string:

```
file:///var/lib/pomerium
```

When using the file backend, ensure the specified directory exists and has appropriate permissions. The in-memory backend (when the field is left empty) does not persist data across restarts.

**Kubernetes:**

See Kubernetes [Storage reference](https://www.pomerium.com/docs/deploy/k8s/reference.md#storage) for more information.

### How to Configure the Postgres Storage Type

The connection string may be provided in either keyword/value format or URI format:

- `host=localhost port=5432 dbname=mydb user=mydbuser`
- `postgresql://[username:password@]host:port/[dbname][?paramspec]`

See the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) for more information on the available options.

**Core:**

| **Config file keys** | **Environment variables** | **Type** |
| :-- | :-- | :-- |
| `databroker_storage_connection_string` | `DATABROKER_STORAGE_CONNECTION_STRING` | `string` |
| `databroker_storage_connection_string_file` | `DATABROKER_STORAGE_CONNECTION_STRING_FILE` | `string` (file path) |

### Examples

```yaml
databroker_storage_connection_string: postgresql://postgres:postgres@database/postgres?sslmode=disable
```

```yaml
databroker_storage_connection_string_file: /run/secrets/db_connection_string
```

```bash
DATABROKER_STORAGE_CONNECTION_STRING=postgresql://postgres:postgres@database/postgres?sslmode=disable
```

```bash
DATABROKER_STORAGE_CONNECTION_STRING_FILE=/run/secrets/db_connection_string
```

**Enterprise:**

`databroker_storage_connection_string` is a bootstrap configuration setting and is not configurable in the Console.

**Zero:**

In Pomerium Zero, configure the connection string in the **Settings → General** section of the Zero console. The storage type is automatically inferred from the connection string format:

```
postgres://user:password@host:5432/database?sslmode=require
```

or

```
postgresql://user:password@host:5432/database?sslmode=require
```

Both `postgres://` and `postgresql://` schemes are supported and automatically detected as Postgres storage.

For production deployments, use a managed Postgres service or ensure your database has proper backups configured. Unlike the in-memory backend, Postgres provides persistent, replicated storage suitable for multi-replica deployments.

**Kubernetes:**

See Kubernetes [Storage reference](https://www.pomerium.com/docs/deploy/k8s/reference.md#storage) for more information.

When using multiple hosts make sure to specify `target_session_attrs=read-write` so that the Databroker does not attempt to write to a read-only replica.

## Clustered Databroker

As of v0.31, Pomerium supports an experimental clustered databroker. The clustered databroker consists of multiple databroker instances. One of those instances is the cluster leader and all the other instances are cluster followers. Databroker commands sent to a follower are forwarded to the leader where they are handled. In addition the clustered databroker supports automatic failure recovery via Raft leader election.

The primary goal of clustering is to provide **resilience** and **high availability**, especially for production deployments. By running multiple databroker instances in a cluster, Pomerium can automatically recover from a single node failure in seconds, minimizing downtime and preventing data loss.

This creates a **self-healing** system that doesn't require manual intervention to recover. It's particularly useful when using the `file` storage backend, as it replicates data across nodes to prevent data loss if a single node goes down.

Consider enabling clustering if you are:

- **Running a high-availability production environment** where minimizing downtime is critical.
- **Using the `file` storage backend** and need a fault-tolerant setup that can survive a single node failure.
- **Deploying across multiple regions or availability zones** to reduce latency.
- **Seeking an infrastructure-agnostic recovery solution** that works consistently across Kubernetes, VMs, and bare metal deployments.

Each databroker instance should have the same shared secret, but its own node ID and its own storage backend. Though not recommended, if the `postgres` storage backend is used, the instances should **not** share the same Postgres database.

The following settings are supported by the clustered databroker:

### Databroker Cluster Node ID

The Databroker Cluster Node ID sets the databroker's node ID. It should correspond to an entry in the Databroker Cluster Nodes option, and it should be unique for each instance of the databroker.

**Core:**

| **Config file keys**         | **Environment variables**    | **Type** |
| :--------------------------- | :--------------------------- | :------- |
| `databroker_cluster_node_id` | `DATABROKER_CLUSTER_NODE_ID` | `string` |

```yaml
databroker_cluster_node_id: node-1
```

```bash
DATABROKER_CLUSTER_NODE_ID=node-1
```

**Enterprise:**

`databroker_cluster_node_id` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

`databroker_cluster_node_id` is not supported in Kubernetes.

### Databroker Cluster Leader ID

The Databroker Cluster Leader ID explicitly sets the leader to one of the databroker instances in the Databroker Cluster Nodes option. When this option is used, the Raft leader elector will not be used and a failure of the leader will not result in automatic failure recovery.

This is for advanced use cases where manual control over leadership is required. Setting a static leader disables the automatic "self-healing" capability of the cluster.

**Core:**

| **Config file keys**           | **Environment variables**      | **Type** |
| :----------------------------- | :----------------------------- | :------- |
| `databroker_cluster_leader_id` | `DATABROKER_CLUSTER_LEADER_ID` | `string` |

```yaml
databroker_cluster_leader_id: node-2
```

```bash
DATABROKER_CLUSTER_LEADER_ID=node-2
```

**Enterprise:**

`databroker_cluster_leader_id` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

`databroker_cluster_leader_id` is not supported in Kubernetes.

### Databroker Cluster Nodes

The Databroker Cluster Nodes option defines the cluster topology of a clustered databroker. It consists of a list of node definitions, each of which has an `id`, `grpc_address` and `raft_address`. Each instance of the databroker that is part of the cluster should have the same cluster nodes definition. To ensure quorum and prevent split-brain scenarios, a cluster using the Raft leader elector requires an odd number of nodes (a minimum of 3 is recommended).

**Core:**

| **Config file keys**       | **Environment variables**  | **Type** |
| :------------------------- | :------------------------- | :------- |
| `databroker_cluster_nodes` | `DATABROKER_CLUSTER_NODES` | `string` |

```yaml
databroker_cluster_nodes:
  - id: node-1
    grpc_address: http://node-1:5443
    raft_address: node-1:5999
  - id: node-2
    grpc_address: http://node-2:5443
    raft_address: node-2:5999
  - id: node-3
    grpc_address: http://node-3:5443
    raft_address: node-2:5999
```

**Enterprise:**

`databroker_cluster_nodes` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

`databroker_cluster_nodes` is not supported in Kubernetes.

### Databroker Raft Bind Address

To use the Raft leader elector, each node needs to set a raft bind address which will be used for TCP connections between each instance. This communication is automatically encrypted using TLS with certificates derived from the shared secret. The `raft_address` in the `databroker_cluster_nodes` option for this node should correspond to this address.

**Core:**

| **Config file keys**           | **Environment variables**      | **Type** |
| :----------------------------- | :----------------------------- | :------- |
| `databroker_raft_bind_address` | `DATABROKER_RAFT_BIND_ADDRESS` | `string` |

```yaml
databroker_raft_bind_address: :5999
```

```bash
DATABROKER_RAFT_BIND_ADDRESS=:5999
```

**Enterprise:**

`databroker_raft_bind_address` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

`databroker_raft_bind_address` is not supported in Kubernetes.