Library Version 18.1.25

Replication PRAGMAs
Prev | Chapter 5. Using Replication with the SQL API | Next

## Replication PRAGMAs

To control replication when using the Berkeley DB SQL interface, you use the following PRAGMAs. For an example of how to use these, see Replication Usage Examples.

### PRAGMA replication

    PRAGMA replication=ON|OFF

Enables the local environment to participate in replication. You only need to specify this PRAGMA once to turn on replication; all future uses of the database will automatically enable replication.

Before invoking this PRAGMA for a brand new database (one that has never been opened), you must invoke the `replication_local_site` PRAGMA and then either the `replication_initial_master` or the `replication_remote_site` PRAGMA. These actions define the way this site fits into the replication group.

If you are enabling replication for an existing database, it must become the initial master for a new replication group. You must invoke the `replication_local_site` PRAGMA followed by the `replication_initial_master` PRAGMA before enabling replication.

If you use this PRAGMA to turn off replication, then replication is completely disabled for the environment. In order to enable replication again, you follow the procedure used to enable replication on an existing database; that is, invoke the `replication_local_site` PRAGMA followed by the `replication_initial_master` PRAGMA, followed by `PRAGMA replication=ON`.

### PRAGMA replication_ack_policy

    PRAGMA replication_ack_policy=all|all_available|none|one|quorum

Sets the replication group's acknowledgement policy. If no policy is specified, then this PRAGMA returns the current acknowledgement policy. This PRAGMA may be called at any time during the life of the application.

Acknowledgement policies are used to describe how permanent messages will be handled. A message is considered to be permanent if the master site has received enough responses (acknowledgements) from its replicas. Once the master is satisfied that a message is permanent, it considers the transaction that generated the message to be complete. Therefore, the acknowledgement policy you set affects your application's write throughput, as well as the durability strength of your transactions.

Message acknowledgements must be returned within a set timeout period. See PRAGMA replication_ack_timeout for information on how to manage this timeout. Also, PRAGMA replication_perm_failed provides useful diagnostic information that you can use to fine-tune your acknowledgement policy.

See Permanent Message Handling for more information on message acknowledgements.

Possible permanent acknowledgement policies are:

- `all`

  All sites belonging to the replication group must acknowledge the message before the generating transaction is considered to be complete. This provides the strongest possible durability guarantee, but also the slowest possible write throughput.

  Note that if any site is shutdown or otherwise cannot be reached due to networking errors, this acknowledgement policy will prevent your application from considering any transactions durable.

- `all_available`

  All currently connected sites must acknowledge the message.

- `none`

  The master will not wait for any message acknowledgements before completing the transaction. This results in the fastest possible write throughput, but also the weakest durability guarantee.

- `one`

  At least one site must acknowledge the message before the transaction is considered to be complete.

- `quorum`

  The master waits until it has received acknowledgements from the minimum number of electable sites sufficient to ensure the record change is durable in the event of an election. This is the default acknowledgement policy.

### PRAGMA replication_ack_timeout

    PRAGMA replication_ack_timeout=<timeout in microseconds>

Sets the replication site's acknowledgement timeout value. If the acknowledgement policy cannot be met within this timeout period, then the encompassing transaction is not considered to be complete. This PRAGMA may be called at any time during the life of the application. The default is 1 second (1000000).

If no timeout is provided, then this PRAGMA returns the replication site's current message acknowledgement timeout value.

For information on specifying acknowledgement policies, see PRAGMA replication_ack_policy. Also, PRAGMA replication_perm_failed provides useful diagnostic information that you can use to fine-tune your acknowledgement timeouts.

### PRAGMA replication_get_master

    PRAGMA replication_get_master

Returns a host/port pair representing the current master. If replication has not yet started, or if the master is currently not known (such as during an election), `NULL` is returned.

### PRAGMA replication_initial_master

    PRAGMA replication_initial_master=ON|OFF

Causes the local environment to start up as a master site. This PRAGMA must be used once and only once in the replicated lifetime of a BDB SQL environment.

This PRAGMA is usually invoked for the first site in a new replication group before the `replication` PRAGMA is invoked and before BDB SQL initially creates the underlying BDB environment for a SQL database. Starting replication on the initial master site establishes the new replication group so that other sites can join it.

However, you must call this PRAGMA when enabling replication for a database that already exists. Doing so causes the existing database to become the replication master for a new replication group.

Note that subsequent election activity can cause other sites in the replication group to become master. Do not assume that the initial master site will remain master indefinitely, or that it will rejoin the replication group as master after a shutdown.

### PRAGMA replication_local_site

    PRAGMA replication_local_site="hostname:port"

Sets the local site information for replication.

### PRAGMA replication_num_sites

    PRAGMA replication_num_sites

Returns the number of sites in the replication group, or `0` if replication has not yet started. Any input provided to this PRAGMA is ignored.

### PRAGMA replication_perm_failed

    PRAGMA replication_perm_failed

Returns the number of times that a permanent message has failed the replication group's acknowledgement policy since the last time this PRAGMA was called. Zero is returned if replication has not yet started.

Every time a permanent message has failed acknowledgement, a transaction was not considered durable and the master waited the full acknowldgement timeout period before returning from its commit. If you are seeing a high number of permanent message acknowledgement failures, then that might represent a significant reduction in your application's write-throughput.

To fix the problem, begin by examining your replicas to make sure they are operating correctly, as well as your network to make sure its performance is what you expect. If all looks well, then you should either reduce your acknowledgement policy (and accept a lessened durability guarantee) or increase your acknowledgement timeout period (which might reduce your write-throughput).

To manage your acknowledgement policies, see PRAGMA replication_ack_policy. To manage your acknowledgement timeout policy, see PRAGMA replication_ack_timeout.

### PRAGMA replication_priority

    PRAGMA replication_priority=<non-0 positive integer>

Sets the site's election priority. When holding elections, if more than one site has the most up-to-date copy of the data then the site with the highest priority will become master. This PRAGMA may be called at any time during the life of the application. The default is 100.

If no priority is provided, then this PRAGMA returns the site's current priority.

### PRAGMA replication_remote_site

    PRAGMA replication_remote_site="hostname:port"

Sets information about a remote helper site in the replication group.

This PRAGMA is needed when a site first joins an existing replication group to specify a site that is already in the replication group. It must be invoked before the `replication` PRAGMA is invoked. This PRAGMA is not needed on the initial master site or when restarting a site that is already a member of the replication group. However, supplying this PRAGMA in those situations does no harm.

Note that the information provided to this PRAGMA can be superseded by normal replication activity over the course of the environment's lifetime.

### PRAGMA replication_remove_site

    PRAGMA replication_remove_site="hostname:port"

Removes the specified site from the replication group. Use this PRAGMA if you truly want to remove the site permanently from the group. It is not desirable to call this PRAGMA if a site has been temporarily shut down or disconnected from the rest of the replication group.

Removing a site from the replication group means that the site is no longer counted towards the total number of sites belonging to the group. This is important when the replication group requires knowledge about whether a quorum has been reached (such as when, for example, elections are held).

### PRAGMA replication_site_status

    PRAGMA replication_site_status

Returns whether the local site is the `MASTER`, `CLIENT`, or `UNKNOWN`.

`UNKNOWN` is returned if replication has not yet started. CLIENT is another term for replica.

### PRAGMA replication_verbose_output

    PRAGMA replication_verbose_output=ON|OFF

If set to TRUE, additional logging information specifically related to replication is created.

### PRAGMA replication_verbose_file

    PRAGMA replication_verbose_file="filename"

Indicates that verbose replication output should be sent to the specified file, as opposed to STDOUT.

Prev | Up | Next
Chapter 5. Using Replication with the SQL API | Home | Displaying Replication Statistics