How-to Guides‎ > ‎

Setting up a read-only replica server

Some editions of Polyhedra allow you to set up a server that acts as a read-only replica of another server. Clients that only want to query the database can connect to the replica rather than the main server. As the main server and the replica will usually be on a different machines, using the replica will reduce the query load on the main server. Of course, keeping the replica up to date will impose an additional load on the main server, but in many case the overall result of using a replica is a more responsive system, especially when some of the queries are complex. (As replicas are read-only, a client will not be able to update the information in the server* - but the client can have a second connection to the main server, and use one server for queries and the second for updates.)

It is easy to set up a read-only replica. The mechanism for keeping a replica up to date is essentially the same as that used to keep the standby up to date in a fault-tolerant configuration, so you need to instruct the main server to set up a port to which the replica server can connect, by defining the journal_service resource. This is most simply done by adding a line such as the following into the section of the poly.cfg file that will be used when starting the main server:

journal_service = 8051

If you are starting up the replica machine on a separate machine, then the configuration file on that machine could look like the following:

type                = rtrdb
replication_service =
data_service        = 8001

When you start up the database server on this machine, using the 'db' entry point, the rtrdb executable will notice that replication_service has been defined, and will assume it is to act as a read-only replica to the server on machine that has opened port 8051 as a journal_service. The main server will then give the replica server a complete copy of the database, and then feed it with information about updates as they occur.

To connect to a replica, the client applications need to quote the port number (and the machine address, if the client is on a different machine) in the normal way, but they also need to confirm that they don't mind that it is the replica they are talking to. This is done by adding [replica] or [any] after the port number, when opening the connection. The former option says that the client wants to to talk to the server, but only if it is running as a replica: this can act as a safety check that the system is set up in the way the client application is expecting. The second option is more forgiving: it says the client application does not care whether what mode the server is running in!

It is possible to set up a read-only replica of a pair of servers in a fault-tolerant configuration, and even to set up replicas in a fan-out or daisy-chain configuration. There is a separate article describing the possibilities, complete with example configuration files,  but we hope this brief note has shown you that it is easy to set up a simple read-only replica that can reduce some of the strain on the main server.

* it is a slight simplification to say that a replica is read-only. To be more accurate, the data replicated from the main server is read-only. However, if certain tables or columns have been defined as transient and local, then the information they contain is not replicated from the main server to the replica, so it is possible for a client application to set the contents of local fields, and to create, update and delete information in local tables. For most purposes, though, it is easiest to think of Polyhedra replica servers as being read-only!