dbreplication

The replication services are administrated with the dbreplication command. It takes the following arguments;

help

If you can specify help or -h argument tand it will display a list of arguments.

# dbreplication help

start

This argument is used to start the specified service. If the service name specified is all, then all configured services will be start on this system.

stop

This argument is used to stop the specified service. If the service name specified is all, then all running services will be stopped on this system.

restart

This argument is used to restart the specified service. If the service name specified is all, then all running services will be restarted on this system.

status

This argument is used to display the current status of the specified service. If the service name specified is all, then the current status for all services will be displayed.

add

This argument is used to add subscribers and peers.

del

This argument is used to delete subscribers and peers.

-d seconds

Specify the delay in seconds between checking for new transactions. Specifying this argument on the command will overwrite the setting specified for DB_REPDELAY in the recital.conf file.

-i

Rebuild the subscriber index used for Peer to Peer replication.

-h

List available command line options (this page).

-l

Turn logging on. Specifying this argument on the command will overwrite the setting specified for DB_REPLOG in the recital.conf file.

-p password

Specify a password for the server the publisher is running on. The password can also be specified in the data source.

-r

Reset the time stamp so all transactions in the queue are processed.

-u username

Specify a user name for the server the publisher is running on. The user name can also be specified in the data source.

Master Slave Configuration

A Master Slave configuration in Recital works with the published data stored in the queue table of the replication database. The Recital engine on the master system (the source of the database changes) writes all updates, inserts, deletes, recalls, packs and zaps into the queue table of the replication database. These transactions are stored in a XML format in the queue table.

Slaves are configured to subscribe to the master and to execute the published events on the slave's local databases. The Master is dumb in this scenario. Once replication has been enabled, all statements are published in the replication queue. If required, you can configure the Master to only publish events that apply to particular databases or tables

Each subscribed slave will get a copy of the changes published since the last time it connected. Slaves keep a record of the position within the published queue that they have read and processed. This means that multiple slaves can be connected to the master and executing different parts of the same published data. Because the slaves control this process, individual slaves can be connected and disconnected from the server without affecting the master's operation. Also, because each slave remembers its position within the published queue, it is possible for slaves to be disconnected, reconnect and then 'catch up' by continuing from the recorded position.

Both the master and each slave must be configured with a unique id. In addition, the slave must be configured with information about the master host name, RTQ database name and position within that file.

Starting MSR

You should start the Master Slave Replication processes in the following order;

Starting Master

On the system specified as the Master you must start the Recital Database Server first with the command;

# dbserver start

Staring Slaves

On the systems specified as Slaves you must start the Subscriber Service with the command;

# dbreplication start

Checking status

Once you have started the subscriber services on the Slaves you can check there current status with the command;

# dbreplication status

An example out put for the Slave Subscriber Service would be;

Subscriber service 'port058' is running on a 60 second delay.
Connected to publisher 'jazz' in a Master Slave configuration.
Current transaction queue size is 0
Last transaction processed was 0 at
Remaining transactions in queue None

Processing Transactions

The subscriber service will sleep the specified number of seconds between each set of transaction. Then it will connect to the master publisher and retrieve all published data since it last connected. For each transaction that it processes it will attempt to open the table in the required mode. For ZAP and PACK transactions it must open the table exclusively, for all others it will open it shared. If it can't find the table specified via the path or can't open it in the required mode an error will be returned.

When the subscriber has to perform changes to existing rows in tables it will use the sync number specified in the transaction to locate the row in the specified table. As all sync number as ascending in order it uses a algorithm to locate the row by truncating the search into sections.

Peer to Peer Configuration

A Peer to Peer configuration is similar in some ways to a MSR in that you still need to define a master publication server. This server will have the master published data which will be updated by the publication service from each peer.

Master Publisher Queue Table

The replication works by storing transactions for publication in the pub_queue table which is stored in the replication database. The replication pup_queue table meta data is defined below and is the same as the local queue table.

Each peer server will keep its own local queue table in its own replication database for updates and changes performed on the server only. In this way each peer it is also the same as a Master in a MSR configuration. For more information on the local queue table see the section Recital Engine Configuration.

The publication service that runs on the master publisher will subscribe to every peer server. It will add all the data from the queue table into the master queue table called pub_queue.

Peer Table

Configuration and status information about each peer is stored in the peer table. The peer table meta data is defined below.

PeerName column

This is the peer name that information is stored for in this row. A row for each peer defined in the replication peers list is inserted into this table. The rows are added when the table is first created and when the publication server is started.

Publication column

This is the publication ID of the peer name specified in this row . This ID is specified during installation of the peer server and is unique between all the systems that the replication services are installed on. It can be found in the recital.conf and is defined by the DB_PUBLICATIONID variable on the system that this peer is installed on. This ID should not be changed once the replication service has been started on the system as it is used to determine which system the transaction was processed on. The first time the subscription service is started on this peer, it will update this row with it's ID. During this process it will check for duplicate IDs and give return an error if one is found.

PeerSyncNum column

This is the last sync number that the publication service processed on this peer server queue table. When the publication service connects to the peer it uses this sync number to know where to start processing from in the queue table. If this value is empty then the publication service will process all transaction in the queue table on the peer server.

PeerLastUpdate column

Last time the publication service updated the peer sync number.

PubSyncNum column

This is the last sync number that the publication service processed for this peer in the pub_queue table. This number is used during conflict resolution to make sure that any conflicts found are in the range of unprocessed records.

PubLastUpdate column

This is the Last time the the publication sync number was updated.

SubSyncNum column

This is the last sync number that the subscription service on this peer processed in the pub_queue table. When the peer's subscriber service connects to the publication service it uses this sync number to know where to start processing from in the pub_queue table. If this value is empty then the subscriber service will process all transaction published in the pub_queue table.

SubLastUpdate column

Last time the subscriber service on the peer updated the subscriber sync number.

Status column

This specifies the current status of the publication service with the peer server. The following values will be used.

Peer table indexes

The peer table contains the following indexes

Starting PPR

On each Peer system you must start the Recital Database Server first with the command;

# dbserver start

The you should start the Peer to Peer Replication processes in the following order;

Starting Master Publication service

On the system specified as the Master you must start the Publication Service first with the command;

# dbreplication start

When the publication service starts it will attempt to connect to all the subscribed peer servers. If they are not on line, then it will set the error status on in the peer table for the server it can't connect to. It will try to establish a connection to unconnected servers each time it wakes to process transactions. So when the server comes back online it will connect and process all waiting transaction since it last connected.

Staring Subscriber Service

On each Peer system you must start the Subscription Service with the command;

# dbreplication start 

The subscriber service will sleep the specified number of seconds between each set of transaction. Then it will connect to the master publisher and retrieve all published data since it last connected. For each transaction that it processes it will attempt to open the table in the required mode. For ZAP and PACK transactions it must open the table exclusively, for all others it will open it shared. If it can't find the table specified via the path or can't open it in the required mode an error will be returned. The Subscriber Service will perform all required locks on tables so existing Recital users can coexist.

Checking status

Once you have started the subscriber services on the peers you can check there current status with the command;

<pre> dbreplication status </pre>

An example out put for the Peer Subscriber Service would be;

<pre> Recital Replication Service on pubserv Subscriber service jazz (02) is running on a 10 second delay. Version 9.5.1 Compiled on Wed Feb 11 10:21:50 EST 2009 Connected to publication pubserv in a Peer to Peer environment. Last SYNCNUM processed was 0100000000000002 at %s </pre>

You can check the status of the publication server y;

<pre> dbreplication status </pre>

An example out put for the Master Publisher Service would be;

<pre> Publication service pubserv is running on a 10 second delay. Version 9.5.1 Compiled on Wed Feb 11 10:21:50 EST 2009

Peer Name: jazz Publication ID: 02 Status: Connected SYNCNUM last update Publication 0100000000003856 2009-02-11 15:59:42 Subscription 0100000000003856 2009-01-30 16:21:03 Peer 0200000000001B9D 2009-02-11 15:59:42

Peer Name: port052 Publication ID: Unknown Status: Connected SYNCNUM last update Publication 0100000000003856 2009-02-11 15:59:42 Subscription Peer 0100000000001CB9 2009-02-11 15:59:42 </pre>