BDR Parameter Reference

From PostgreSQL wiki

Jump to: navigation, search

The Bi-directional replication (BDR) feature for PostgreSQL adds a number of parameters. These are discussed in the BDR quick-start guide but are covered in more detail here.


Core server parameters used with BDR

shared_preload_libraries = 'bdr'

To load support for receiving changes on a downstream master, the bdr library must be added to the existing ‘shared_preload_libraries’ parameter. This loads the bdr library during postmaster start-up and allows it to create the required background worker(s).

Upstream masters don't need to load the bdr library unless they're also operating as a downstream master as is the case in a BDR configuration.


Setting this parameter to "on" enables commit timestamp tracking, which is used to implement last-UPDATE-wins conflict resolution.

It is also required for use of the pg_get_transaction_committime function.

This parameter does not exist in PostgreSQL 9.4, it is added by the BDR patch.

Bi-directional replication, or BDR, is a PostgreSQL enhancement project that is available as a usable release in its own right.

See BDR User Guide for details.

wal_level = 'logical'

The ‘logical’ setting for wal_level includes everything that the hot_standby setting does and adds additional details required for logical changeset decoding to the write-ahead logs. This must be enabled to use BDR.

This additional information is consumed by the upstream-master-side xlog decoding worker. Downstream masters that do not also act as upstream masters do not require wal_level to be increased above the default 'minimal'.

wal_level is documented in the main PostgreSQL manual.


The new parameter max_replication_slots has been added for use on both upstream and downstream masters. This parameter controls the maximum number of logical replication slots - upstream or downstream - that this cluster may have at a time. It must be set at postmaster start time.

As logical replication slots are persistent, slots are consumed even by replicas that are not currently connected. Slot management is discussed in Starting, Stopping and Managing Replication.

max_replication_slots should be set to the sum of the number of logical replication upstream masters this server will have plus the number of logical replication downstream masters will connect to it it.


Logical replication hasn't altered the max_wal_senders parameter, but it is important in upstream masters for logical replication and BDR because every logical sender consumes a max_wal_senders entry.

You should configure max_wal_senders to the sum of the number of physical and logical replicas you want to allow an upstream master to serve. If you intend to use pg_basebackup you should add at least two more senders to allow for its use.

Like max_replication_slots, max_wal_senders entries don't cost a large amount of memory, so you can overestimate fairly safely.

max_wal_senders is documented in the main PostgreSQL documentation.

BDR extension parameters

The bdr.bdr_connections parameter is required to use BDR. Other bdr. extension parameters are optional.


A comma-separated list of upstream master connection names is specified in bdr.connections. These names must be simple alphanumeric strings. They are used when naming the connection in error messages, configuration options and logs, but are otherwise of no special meaning.

A typical two-upstream-master setting might be:

bdr.connections = 'upstream1, upstream2'

Each connection takes parameters; see #BDR extension per-connection parameters.


This boolean option controls the synchronous_commit setting for BDR apply workers. It defaults to on.

If set to off, BDR apply workers will perform async commits, allowing PostgreSQL to considerably improve throughput. It is safe unless you intend to run BDR with synchronous replication, in which case bdr.synchronous_commit must be left on.


Sets the default for bdr.<conname>_apply_delay for all configured connections.

Primarily useful for debugging.


Boolean, controls whether detected BDR conflicts get logged to the bdr.bdr_conflict_history table. See Conflict logging for details.


Has no effect without bdr.<conname>_init_replica=on for one or more connections.

Specifies the path to a temporary storage location, writable by the postgres user, that has enough storage space to contain a complete dump of the database at bdr.<connection_name>_dsn for each configured connection with init_replica enabled.

Only used during initial bringup.


Allocates shared memory space for BDR worker configuration information. You can ignore this parameter at the moment.

This parameter is auto-calculated from the number of bdr.connections, with the assumption that each connection has a separate database and thus needs two connections. This wastes a small amount of shared memory, but the impact is minimal. It isn't otherwise useful - it'll be important when BDR is enhanced to allow new connections to be added at runtime, but isn't currently worth paying attention to.

BDR extension per-connection parameters

Each entry in bdr.bdr_connections has parameters. At least bdr.<connname>_dsn is required for each entry; others are optional.


Each connection name must have at least a data source name specified using the bdr.<connection_name>_dsn parameter. The DSN syntax is the same as that used by libpq so it is not discussed in further detail here. A dbname for the database to connect to must be specified; all other parts of the DSN are optional.

The local (downstream) database name is assumed to be the same as the name of the upstream database being connected to, though future versions will make this configurable.

For the above two-master setting for bdr.connections the DSNs might look like:

bdr.upstream1_dsn = 'host= user=postgres dbname=replicated_db'
bdr.upstream2_dsn = 'host= user=postgres dbname=replicated_db'


This parameter, which defaults to zero, causes the application of received transactions to be delayed by the specified number of milliseconds.

It is mostly useful for testing and debugging purposes, but may also be used to provide a replica of the database at a known point in the recent past.


This parameter defaults to off.

There are two reasons for setting it to on:

  1. If the database was initialized using initdb, it will cause BDR to dump the database pointed to by this bdr.<connection_name>.dsn before starting replication and apply the dump to the local database, which must be empty.

    The dump is guaranteed to be consistent with the start point for replication.

    The bdr.<connection_name>_replica_local_dsn parameter will become required for this connection in this scenario.

  1. If pg_basebackup was used to initialize database, the bdr_init_copy utility and BDR plugin itself will use this setting to determine which node to use with additional synchronization to a consistent point.

    See Starting from pg_basebackup for more details.

    The bdr.<connection_name>_replica_local_dsn parameter is not needed in this scenario.


Ignored unless _init_replica is on for this connection, required if it is on.

A connection string that is passed to the script at bdr.<connection_name>_replica_script_path, telling it which local database to connect to in order to apply the dump of the remote DB.

The connection string is only visible to superusers, and should specify a superuser connection. You may include a password in the connection string if required, or put it in the separate .pgpass file for the postgres user.

Personal tools