|
ITTIA DB SQL C API
5.4.0
|
Replication is used to distribute changes from one database file to another.
To enable replication:
| #define DB_REP_ADDRESS_NONE 0 |
Special value for a peer address column: do not replicate the row with any peer.
| #define DB_REP_ADDRESS_ALL INT32_MAX |
Special value for a peer address column: share row with all replication peers.
| #define DB_REP_MODE_NONE 0 |
Do not participate in replication.
| #define DB_REP_MODE_IN 1 |
Receive changes from replication peers.
| #define DB_REP_MODE_OUT 2 |
Send changes to replication peers.
| #define DB_REP_MODE_INOUT (DB_REP_MODE_IN | DB_REP_MODE_OUT) |
Send and receive changes.
| #define DB_REP_STATE_LOCAL 0 |
Last change was local.
| #define DB_REP_STATE_DELIVERY 1 |
Last change was local, the row delivery is pending.
| #define DB_REP_STATE_REMOTE 2 |
Last change was remote.
| #define DB_REP_STATE_DELIVERED 3 |
Changes were delivered to a peer.
| #define DB_REP_STATE_REFUSED 4 |
Changes were refused by a peer due to conflicts.
| #define DB_REP_STATE_IGNORED 5 |
Changes were ignored by a peer.
| #define DB_REP_RESOLVE_PRIORITY_MIN 0x00001 |
Minimum possible priority.
| #define DB_REP_RESOLVE_PRIORITY_MAX 0x000fe |
Maximum possible priority.
| #define DB_REP_RESOLVE_ACCEPT 0x00000u |
Always accept conflicting changes.
| #define DB_REP_RESOLVE_REFUSE 0x000ffu |
Always refuse conflicting changes.
| #define DB_REP_RESOLVE_PRIORITY_MASK 0x000ffu |
Priority bits for insert_resolve, update_resolve, and delete_resolve.
| #define DB_REP_RESOLVE_EXCL 0x01000u |
Perform this operation exclusively.
Otherwise, insert will update when the row already exists and update will insert when the row doesn't exist.
| #define DB_REP_RESOLVE_DISABLE 0x02000u |
Disable input operation.
| #define DB_REP_RESOLVE_NOSEND 0x04000u |
Do not generate operation.
| #define DB_REPTYPE_NONE 0 |
Replication with peer is disabled.
| #define DB_REPTYPE_ADHOC 1 |
Ad hoc replication by explicit exchange.
| #define DB_REPTYPE_SYNC 2 |
Sync replication on commit.
| db_result_t db_rep_table_query | ( | db_t | hdb, |
| const db_objname_t * | table_name, | ||
| db_rep_table_info_t * | rep_info | ||
| ) |
Read current replication settings for a table.
| hdb | Database handle. | |
| table_name | Name of the table. | |
| [out] | rep_info | Destination for replication info. |
On failure, one of the following error codes is set:
If replication has not been enabled for the table, rep_mode is set to DB_REP_MODE_NONE and all other members are initialized to default values.
| db_result_t db_rep_table_set | ( | db_t | hdb, |
| const db_objname_t * | table_name, | ||
| const db_rep_table_info_t * | rep_info, | ||
| db_flags_t | flags | ||
| ) |
Set replication settings for a table.
| hdb | Database handle. |
| table_name | Name of the table. |
| rep_info | Replication info. |
| flags | Reserved for future use. Set to 0. |
On failure, one of the following error codes is set:
Each individual table that should participate in replication must be configured with this function. Only tables stored on disk can participate in replication.
Set rep_mode to one of:
insert_resolve, update_resolve, and delete_resolve control what kind of changes will be accepted from peer databases. Each member contains both a priority setting and a set of flags. The priority bits are accessed with DB_REP_RESOLVE_PRIORITY_MASK and can be set to one of:
The following flags can also be set for each of the resolve members:
peer_column, state_column, and rid_column must either be blank or identify existing columns of type DB_VARTYPE_SINT32. When a row is received from a peer database, these columns are populated with information about the source of the data. The peer_column contains the peer address configured for the peer database. The rid_column identifies the row in the peer database from which the data was obtained. However row ID values may be reused when rows are deleted in the peer.
When rows are sent to a peer, the peer only receives rows that are assigned to it using the peer_column, or that are assigned to no peer. If a peer_column is not configured, or if the peer_column is null for a particular row, all peers will receive the changes.
The state_column is automatically set to one of the following values whenever a row is modified, received, or sent:
rep_index must either be blank or identify an existing index. If blank, the table's primary key is used to identify rows.
| db_result_t db_rep_snapshot | ( | db_t | hdb, |
| const db_objname_t * | table, | ||
| const db_objname_t * | peer_name, | ||
| db_flags_t | flags | ||
| ) |
Send or receive a snapshot of a table in another database.
| hdb | Database handle. |
| table | Name of a table that exists in both hdb and the peer database. |
| peer_name | Name of a database peer that is configured in hdb. |
| flags | Direction of data transfer. One of:
|
The contents of table are immediately copied to the destination database, and any existing data is overwritten. The destination is either hdb or the replication peer referenced by peer_name.
The tables in each database may differ in structure, with some limitations. Both tables must have the same primary key. Only common fields will be copied, and all other fields in the destination table should be nullable. Common fields may have different types, provided that type conversion is possible.
Only rows that differ between the two tables are copied in full. The snapshot will complete more quickly if the tables are already identical.
The table does not need to be configured for replication in either database. However, special columns, such as the peer address, will only be set correctly if replication is configured for the table.
| db_result_t db_rep_snapshot_ex | ( | db_t | hdb, |
| const db_objname_t * | table, | ||
| const db_objname_t * | peer_name, | ||
| const db_rep_snapshot_info_t * | snapshot_info | ||
| ) |
Send or receive a snapshot of a table in another database.
| hdb | Database handle. |
| table | Name of a table that exists in both hdb and the peer database. |
| peer_name | Name of a database peer that is configured in hdb. |
| snapshot_info | Snapshot settings, including direction and authentication. If NULL, the direction is DB_REP_MODE_OUT. |
The contents of table are immediately copied to the destination database, and any existing data is overwritten. The destination is either hdb or the replication peer referenced by peer_name.
The tables in each database may differ in structure, with some limitations. Both tables must have the same primary key. Only common fields will be copied, and all other fields in the destination table should be nullable. Common fields may have different types, provided that type conversion is possible.
Only rows that differ between the two tables are copied in full. The snapshot will complete more quickly if the tables are already identical.
The table does not need to be configured for replication in either database. However, special columns, such as the peer address, will only be set correctly if replication is configured for the table.
| db_result_t db_rep_peerdef_init | ( | db_rep_peerdef_t * | peerdef | ) |
Initialize a peer definition data structure to default values.
| peerdef | Replication peer definition. |
| db_result_t db_rep_peerdef_destroy | ( | db_rep_peerdef_t * | peerdef | ) |
Destroy a peer definition data.
| peerdef | Replication peer definition. |
| db_result_t db_rep_create_peer | ( | db_t | hdb, |
| const db_objname_t * | peer_name, | ||
| const db_rep_peerdef_t * | peerdef | ||
| ) |
Create a replication peer.
| hdb | Database handle. |
| peer_name | Name of the replication peer. |
| peerdef | Replication peer definition. |
On failure, one of the following error codes is set:
After a peer is created, replication is performed by calling
The replication peer definition is stored in the database file and can be accessed by name. The peer name must be unique in this database only.
The replication address assigned to the peer should be unique across all databases that might participate in the same replication network.
| db_result_t db_rep_drop_peer | ( | db_t | hdb, |
| const db_objname_t * | peer_name | ||
| ) |
| db_result_t db_rep_describe_peer | ( | db_t | hdb, |
| const db_objname_t * | peer_name, | ||
| db_rep_peerdef_t * | peerdef | ||
| ) |
Describe a previously configured replication peer.
| hdb | Database handle. | |
| peer_name | Name of the replication peer. | |
| [out] | peerdef | Replication peer definition. |
On failure, one of the following error codes is set:
| db_result_t db_rep_alter_peer | ( | db_t | hdb, |
| const db_objname_t * | peer_name, | ||
| const db_rep_peerdef_t * | peerdef | ||
| ) |
Alter a previously configured replication peer.
| hdb | Database handle. |
| peer_name | Name of the replication peer. |
| peerdef | Replication peer definition. |
On failure, one of the following error codes is set:
| db_result_t db_rep_peer_credentials | ( | db_t | hdb, |
| const db_objname_t * | peer_name, | ||
| const db_auth_info_t * | auth_info, | ||
| db_flags_t | flags | ||
| ) |
Set authorization credentials for a replication peer.
| hdb | A database connection. |
| peer_name | A peer of hdb. |
| auth_info | Authorization credentials for the peer. |
| flags | Reserved for future use. Set to 0. |
Credentials are discarded when hdb is shutdown.
On failure, one of the following error codes is set:
| db_result_t db_rep_exchange | ( | db_t | hdb, |
| const db_objname_t * | peer_name, | ||
| db_flags_t | flags | ||
| ) |
Perform a row exchange with a replication peer.
| hdb | Database handle. |
| peer_name | Name of the replication peer. |
| flags | Reserved for future use. Set to 0. |
On failure, one of the following error codes is set:
Only tables that are configured for replication in both this and the peer database will participate in the exchange. The direction of replication for both databases is respected.
Only peers that are configured for ad hoc replication (DB_REPTYPE_ADHOC) can use this function.
Replication is performed by opening a connection to the peer database and exchanging replication log records between the two databases.
| db_result_t db_rep_exchange_ex | ( | db_t | hdb, |
| const db_objname_t * | peer_name, | ||
| const db_rep_exchange_t * | options | ||
| ) |
Perform a row exchange with a replication peer.
| hdb | Database handle. |
| peer_name | Name of the replication peer. |
| options | Replication exchange options. |
On failure, one of the following error codes is set:
Only tables that are configured for replication in both this and the peer database will participate in the exchange. The direction of replication for both databases is respected.
Only peers that are configured for ad hoc replication (DB_REPTYPE_ADHOC) can use this function.
Replication is performed by opening a connection to the peer database and exchanging replication log records between the two databases.
| db_result_t db_rep_config_init | ( | db_rep_config_t * | rep_config | ) |
Initialize replication settings.
| rep_config | Replication configuration data structure to initialize. |
On failure, one of the following error codes is set:
| db_result_t db_rep_config_destroy | ( | db_rep_config_t * | rep_config | ) |
Destroy replication settings.
| rep_config | Replication configuration data structure to initialize. |
On failure, one of the following error codes is set:
| db_result_t db_rep_set_config | ( | db_t | hdb, |
| const db_rep_config_t * | rep_config | ||
| ) |
Configure replication settings for a database.
| hdb | Database handle. |
| rep_config | Replication configuration settings. |
Settings are saved persistently in the database file.
The replication address identifies the database uniquely among replication peers.
This function enables replication logging. When replication logging is active, the database log file is periodically rotated to a new file. Old log files are removed only when all records have been exchanged with all active peers.
Set rep_config->rep_address to DB_REP_ADDRESS_NONE to disable replication logging.
On failure, one of the following error codes is set:
| db_result_t db_rep_get_config | ( | db_t | hdb, |
| db_rep_config_t * | rep_config | ||
| ) |
Get replication settings stored in a database.
| hdb | Database handle. | |
| [out] | rep_config | Replication configuration settings. |
On failure, one of the following error codes is set: