Plugin used to perform replication.

Replication typeSynchronous, asynchronous

Syntax

plugin = plugin

Defaultempty (use built-in replication)

Leaving/setting this empty will use the built-in (default) replication.

Example

# Use plugin CustomReplication for all databases
database
{
  plugin = CustomReplication
}
 
# Revert to default replication for a specific database
database /path/to/example.fdb
{
  plugin =
}

Pattern for tables to include in replication.

Replication typeSynchronous, asynchronous

Syntax

include_filter = [ <sql-regular-expression> ]
 
<sql-regular-expression> ::=
  !! See Syntax: SQL Regular Expressions !!

Defaultempty (all tables of publication set)

By default, all tables in the publication set of the database are replicated. The include_filter can be used to reduce this to a subset (only those matching the include_filter — and not matching the Section 6.2.3, “exclude_filter”).

The publication set of the database can be configured with ALTER DATABASE, CREATE TABLE and ALTER TABLE. This is not covered by this reference. For further details, see Setting Up Replication in the Firebird 4.0 Release Notes.

The include_filter uses the SQL regular expression syntax, described in Syntax: SQL Regular Expressions in the Firebird 5.0 Language Reference.

Example

database /path/to/example.fdb
{
  # Only replicate tables with prefix DAT_, and tables CUSTOMER and ORDER
  include_filter = DAT\_%|CUSTOMER|ORDER
}

See alsoSection 6.2.3, “exclude_filter”

Pattern for tables to exclude in replication.

Replication typeSynchronous, asynchronous

Syntax

exclude_filter = [ <sql-regular-expression> ]
 
<sql-regular-expression> ::=
  !! See Syntax: SQL Regular Expressions !!

Defaultempty (exclude nothing)

By default, all tables in the publication set of the database are replicated. The exclude_filter can be used to reduce this to a subset (exclude those matching the exclude_filter — possibly already limited to those matching the Section 6.2.2, “include_filter”).

The publication set of the database can be configured with ALTER DATABASE, CREATE TABLE and ALTER TABLE. This is not covered by this reference. For further details, see Setting Up Replication in the Firebird 4.0 Release Notes.

The exclude_filter uses the SQL regular expression syntax, described in Syntax: SQL Regular Expressions in the Firebird 5.0 Language Reference.

Example

database /path/to/example.fdb
{
  # Do not replicate tables with prefix DAT_, and tables CUSTOMER and ORDER
  exclude_filter = DAT\_%|CUSTOMER|ORDER
}

See alsoSection 6.2.2, “include_filter”

Configures if all errors and warnings are logged to replication.log.

Replication typeSynchronous, asynchronous

Syntax

log_errors = Boolean

Defaulttrue

This setting only affects error logging on the primary side. For error logging on the replica side, see Section 6.2.20, “verbose_logging”.

See alsoSection 6.2.20, “verbose_logging”

Configures if replication errors are reported to the client application.

Replication typeSynchronous, asynchronous

Syntax

report_errors = Boolean

Defaultfalse

Configures if a replication error disables replication.

Replication typeSynchronous, asynchronous

Syntax

disable_on_error = Boolean

Defaulttrue

Primary configuration items of built-in replication

The following configuration items are specific to configure the primary side of the built-in (default) replication. If you use a third-party replication plugin, consult the documentation of your replication plugin for its configuration items.

Size of in-memory buffer to accumulate changes that can be deferred until transaction commit/rollback.

Replication typeSynchronous, asynchronous

Syntax

buffer_size = integer

UnitByte

Default1048576 (1 MiB)

The bigger this value, the less concurrent disk access (related to journal IOPS) happens.

For synchronous replication, it also affects number of network round-trips between primary and replica hosts. However, a larger buffer results in a longer replication checkpoint (delay to synchronize the original database with its replica at commit).

Directory to store replication journal files.

Replication typeAsynchronous

Syntax

journal_directory = path

The journal directory is a working directory where the Firebird server stores its journal files for the primary for asynchronous replication.

This setting should not be specified when only using synchronous replication.

The journal directory is for use by the primary only; this directory and its contents should not be referenced, accessed or modified by the replica (or anything else).

When asynchronous replication is used, journal files (or, replication segments) are moved to the journal archive directory or using a custom archiving command when they are ready to be replicated to (consumed by) the replica.

See alsoSection 6.2.13, “journal_archive_directory”, Section 6.2.14, “journal_archive_command”, Section 6.2.18, “journal_source_directory”

Prefix for replication journal file names.

Replication typeAsynchronous

Syntax

journal_file_prefix = string

Defaultempty (use database filename)

The journal filename is generated by concatenating the prefix with a sequential number.

If not specified, the database filename (without path) is used as a prefix.

Maximum allowed size for a single replication segment.

Replication typeAsynchronous

Syntax

journal_segment_size = integer

UnitByte

Default16777216 (16 MiB)

See alsoSection 6.2.15, “journal_archive_timeout”

Maximum allowed number of full replication segments pending archiving.

Replication typeAsynchronous

Syntax

journal_segment_count = integer

UnitReplication segments

Default8

Once this limit is reached, the replication process is temporarily delayed to allow the archiving to catch up. If any of the full segments are not archived within one minute, replication fails with an error.

Zero (0) means an unlimited number of segments pending archiving.

Delay, in milliseconds, to wait before the changes are synchronously flushed to the journal (usually at commit time).

Replication typeAsynchronous

Syntax

journal_group_flush_delay = integer

UnitMillisecond

Default0 (no delay)

This setting allows multiple concurrently committing transactions to amortise I/O costs by sharing a single flush operation.

Zero (0) means no delay, i.e. group flushing is disabled.

Directory to store archived replication segments.

Replication typeAsynchronous

Syntax

journal_archive_directory = path

The journal archive directory is used to store replication segments (journal files) that are ready to be consumed by a replica using asynchronous replication.

Firebird will automatically move replication segments to this directory, unless Section 6.2.14, “journal_archive_command” is defined.

If you have a single replica, the journal archive directory can be used directly by the replica (in Section 6.2.18, “journal_source_directory”). This can — for example — be done by mounting or otherwise sharing the directory between both hosts.

If you have multiple replicas, each replica must have its own copy of the journal archive. Replicas will delete journal files they no longer need, which can conflict with the needs of another replica. Make sure that each journal file created by Firebird in this directory is copied to a location unique to a replica, or use the Section 6.2.14, “journal_archive_command” instead.

The value of this configuration item also defines the $(archpathname) macro used in Section 6.2.14, “journal_archive_command”.

This configuration item can be omitted when Section 6.2.14, “journal_archive_command” is specified without the $(archpathname) macro.

See alsoSection 6.2.14, “journal_archive_command”, Section 6.2.18, “journal_source_directory”

Program (complete commandline with arguments) that is executed when a replication segment is full and needs archiving.

Replication typeAsynchronous

Syntax

journal_archive_command = string

This program must return exit-code zero only if archiving has been performed successfully. In particular, it must return a non-zero exit-code if the target archive already exists.

Special predefined macros are available:

$(filename)

filename (without path) of the journal segment being archived

$(pathname)

full path of the journal segment being archived; same as Section 6.2.8, “journal_directory” + $(filename)

$(archivepathname)

suggested full path for the archived segment; same as Section 6.2.13, “journal_archive_directory” + $(filename)

If journal_archive_command is used without the $(archivepathname) macro, the configuration item Section 6.2.13, “journal_archive_directory” can be omitted.

A simple example using standard OS commands for archiving

# Linux
journal_archive_command = "test ! -f $(archivepathname) && cp $(pathname) $(archivepathname)"
 
# Windows
journal_archive_command = "copy $(pathname) $(archivepathname)"

See alsoSection 6.2.8, “journal_directory”, Section 6.2.13, “journal_archive_directory”

Timeout, in seconds, to wait until an incomplete (not full) segment is scheduled for archiving.

Replication typeAsynchronous

Syntax

journal_archive_timeout = integer

UnitSecond

Default60 (1 minute)

This configuration item can be used to minimize the replication gap if the database is modified rarely.

Zero (0) means no intermediate archiving, i.e. segments are archived only after reaching their maximum size (defined by Section 6.2.10, “journal_segment_size”).

See alsoSection 6.2.10, “journal_segment_size”

Connection information to the replica database (for synchronous replication).

Replication typeSynchronous

Syntax

sync_replica = <connection-specification>
 
<connection-specification> ::=
    [username[:password]]@<database-url>
  | <database-url>
    '{'
      [ <key> = <value> <new-line> ]...
    '}'
 
<database-url> ::=
  !! Normal Firebird database URL formats !!

Multiple entries are allowed (for different synchronous replicas).

The value of sync_replica is either:

1. a simple value with the database URL, optionally prefixed with a username and an optional password, or

2. a scoped value where the simple value is only a database URL, and configuration of username and password is done through key-value items within the scope.

To specify a username or password containing : or @, you must use a scoped value.

At most one username* and one password* key may be specified.

If username_file or password_file have a relative path, the path is resolved against the Firebird root directory.

Example

# As simple value
sync_replica = john:smith@server2:replica
 
# As scoped value
sync_replica = server2:replica
{
  username = john
  password = smith
}
 
# Password sourced from file
sync_replica = server2:replica
{
  username = john
  password_file = /path/to/password.txt
}
 
# Username and password sourced from environment
sync_replica = server2:replica
{
  username_env = REPLICA_USERNAME
  password_env = REPLICA_PASSWORD
}

Replica side

The following settings only affect the replica side (a.k.a. secondary or slave) of replication.

Configures if changes applied to the replica will be subject to further replication (if any configured).

Replication typeSynchronous, asynchronous

Syntax

cascade_replicaton = Boolean

Defaultfalse

This setting only has an effect if the replica is also configured as a primary.

If disabled (the default), changes applied from incoming replication are not replicated. Only changes directly applied to the (read-write) replica (i.e. changes to the database by means other than replication) will be replicated to the next replica(s).

If enabled, the changes applied from incoming replication and changes directly applied to the replica will be replicated to the next replica(s).

Directory to search for the journal files to be applied to the replica.

Replication typeAsynchronous

Syntax

journal_source_directory = path

The replica searches the journal source directory for files to apply.

If there is only a single replica, the directory specified in this configuration item can be the same directory as specified in Section 6.2.13, “journal_archive_directory” of the primary. This can — for example — be done by mounting or otherwise sharing the directory between both hosts.

If you have multiple replicas, each replica must have its own copy of the journal archive, and use its own directory. Replicas will delete journal files they no longer need, which can conflict with the needs of another replica.

See alsoSection 6.2.13, “journal_archive_directory”, Section 6.2.14, “journal_archive_command”

Filter to limit replication to a particular source database (based on its GUID).

Replication typeAsynchronous

Syntax

source_guid = <quoted-guid>
 
<quoted-guid> ::= '"{' guid '}"'

By default, asynchronous replication will (try to) apply all journal files — from any primary — that shows up in the Section 6.2.18, “journal_source_directory”.

This setting can be used to only apply journal files from a specific primary, using its database GUID (e.g. as shown on the header page of gstat -h).

Example

source_guid = "{8FA6D945-BE7E-4376-86D7-E4AAF3889FAF}"

See alsoSection 6.2.18, “journal_source_directory”

Configures if replication.log contains a detailed log of operations performed by replication.

Replication typeAsynchronous

Syntax

verbose_logging = Boolean

Defaultfalse

If disabled (the default), only errors and warnings are logged.

This setting only affects logging on the replica side. For error logging on the primary side, see Section 6.2.4, “log_errors”.

See alsoSection 6.2.4, “log_errors”

Timeout (in seconds) to wait before scanning for new replication segments.

Replication typeAsynchronous

Syntax

apply_idle_timeout = integer

UnitSecond

Default10 (10 seconds)

When all existing journal files have been applied, replication waits for the specified duration before checking if new files have arrived in Section 6.2.18, “journal_source_directory”.

See alsoSection 6.2.18, “journal_source_directory”

Timeout (in seconds) to wait before retrying queued replication segments after an error.

Replication typeAsynchronous

Syntax

apply_error_timeout = integer

UnitSecond

Default60 (1 minute)

After an error when applying a replication segment, replication is paused for the specified duration before retrying.

The server disconnects from the replica database, sleeps for the specified timeout, then reconnects and tries to reapply the latest segments from the point of failure.