Skip to main content
Version: vNext (upcoming release)

Databroker Storage Settings

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.

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.

How to Configure​

Config file keysEnvironment variablesTypeDefault
databroker_storage_typeDATABROKER_STORAGE_TYPEstringmemory

Examples​

databroker_storage_type: postgres
DATABROKER_STORAGE_TYPE=postgres

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 file or postgres.

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:

databroker_storage_connection_string: file:///var/pomerium/databroker
DATABROKER_STORAGE_CONNECTION_STRING=file:///var/pomerium/databroker

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 for more information on the available options.

Config file keysEnvironment variablesType
databroker_storage_connection_stringDATABROKER_STORAGE_CONNECTION_STRINGstring
databroker_storage_connection_string_fileDATABROKER_STORAGE_CONNECTION_STRING_FILEstring (file path)

Examples​

databroker_storage_connection_string: postgresql://postgres:postgres@database/postgres?sslmode=disable
databroker_storage_connection_string_file: /run/secrets/db_connection_string
DATABROKER_STORAGE_CONNECTION_STRING=postgresql://postgres:postgres@database/postgres?sslmode=disable
DATABROKER_STORAGE_CONNECTION_STRING_FILE=/run/secrets/db_connection_string
tip

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.

Config file keysEnvironment variablesType
databroker_cluster_node_idDATABROKER_CLUSTER_NODE_IDstring
databroker_cluster_node_id: node-1
DATABROKER_CLUSTER_NODE_ID=node-1

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.

warning

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.

Config file keysEnvironment variablesType
databroker_cluster_leader_idDATABROKER_CLUSTER_LEADER_IDstring
databroker_cluster_leader_id: node-2
DATABROKER_CLUSTER_LEADER_ID=node-2

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).

Config file keysEnvironment variablesType
databroker_cluster_nodesDATABROKER_CLUSTER_NODESstring
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

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.

Config file keysEnvironment variablesType
databroker_raft_bind_addressDATABROKER_RAFT_BIND_ADDRESSstring
databroker_raft_bind_address: :5999
DATABROKER_RAFT_BIND_ADDRESS=:5999
Feedback