Simple Replication Agent tutorial

Simple tutorial to replicate data between two FairCom servers running on the same computer

This tutorial sets up an unmanaged replication agent (for FairCom DB V12 (released in 2020) or newer) with both the Source and Target FairCom DB instances residing on the same machine. This example highlights a common use case in which the Replication Agent runs within the Target instance to pull transaction changes from the Source instance. This places the more time-consuming insert operations on the Target instance, where they are most efficient. Note that this tutorial also works for FairCom RTG V4 or newer. It is safe to replace FairCom DB references with FairCom RTG. 

  1. Install a Source (primary) server environment. This is the <faircom>\server directory of your installed FairCom software.
  2. Create a secondary server environment called Target. Create a <faircom>\target directory and copy the following folders and their contents from the source <faircom> directory into the <faircom>\target directory you just created.
    1. config
    2. data
    3. server
    4. tranlogs
  3. Configure the Source server by adding the following keyword to the Source server <faircom>\config\ctsrvr.cfg file: REPL_NODEID 10.0.0.1
    1. REPL_NODEID is not the IP address of the running machine. It is just an ID that the connecting replication agents will use to uniquely identify the server. Leave it unchanged for this tutorial.
  4. Configure the Target server to make the FairCom ISAM and SQL server communication ports unique (this is needed so we can execute both the Source and Target server instances on the same computer) and enable the replication agent. 
    1. In <faircom>\target\config\ctsrvr.cfg, change SERVER_NAME FAIRCOMS to SERVER_NAME FAIRCOMT.
    2. In <faircom>\target\config\ctsrvr.cfg, change SQL_PORT 6597 to SQL_PORT 6598.
    3. Add this line to <faircom>\target\config\ctsrvr.cfg (this is needed for replication): REPL_NODEID 10.0.0.2.
    4. In <faircom>\target\config\services.json, change:
      1. "serviceName": "https8443",
"description": "Port 8443 using TLS-secured HTTPS protocol for REST …	
"port": 8443,
      2. to:
      3. "serviceName": "https8444",
"description": "Port 8444 using TLS-secured HTTPS protocol for REST …	
"port": 8444,
    5. Set the Target ctagent in <faircom>\target\config\services.json to true (this is needed for replication):
      1. "serviceName": "ctagent",
"serviceLibrary": "./agent/ctagent.dll",
"enabled": false
      2. to:
      3. "serviceName": "ctagent",
"serviceLibrary": "./agent/ctagent.dll",
"enabled": true
    6. Change the port in the Target <faircom>\target\config\services.json from:
      1. {
	"serviceName": "mqtt1883",
	"description": "Port 1883 using insecure MQTT protocol for the MQTT broker on all TCP/IP addresses bound to this server",
	"port": 1883,
	"protocol": "mqtt",
	"enabled": true
},
	{
		"serviceName": "mqtts8883",
		"description": "Port 8883 using TLS-secured MQTTS protocol for the MQTT broker on all TCP/IP addresses bound to this server",
		"port": 8883,
		"protocol": "mqtts",
		"enabled": true,
		"tls": {
			"serverCertificateFilename": "./web/fccert.pem"
		}
	},
	{
		"serviceName": "mqttws9001",
		"description": "Port 9001 using WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
		"port": 9001,
		"protocol": "mqttws",
		"enabled": true
	},
	{
		"serviceName": "mqttwss9002",
		"description": "Port 9002 using TLS-secured WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
		"port": 9002,
		"protocol": "mqttwss",
		"enabled": true,
		"tls": {
			"serverCertificateFilename": "./web/fccert.pem"
		}
	}
      2. to:
      3. {
	"serviceName": "mqtt1884",
	"description": "Port 1884 using insecure MQTT protocol for the MQTT broker on all TCP/IP addresses bound to this server",
	"port": 1884,
	"protocol": "mqtt",
	"enabled": true
},
	{
		"serviceName": "mqtts8884",
		"description": "Port 8884 using TLS-secured MQTTS protocol for the MQTT broker on all TCP/IP addresses bound to this server",
		"port": 8884,
		"protocol": "mqtts",
		"enabled": true,
		"tls": {
			"serverCertificateFilename": "./web/fccert.pem"
		}
	},
	{
		"serviceName": "mqttws9003",
		"description": "Port 9003 using WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
		"port": 9003,
		"protocol": "mqttws",
		"enabled": true
	},
	{
		"serviceName": "mqttwss9004",
		"description": "Port 9004 using TLS-secured WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
		"port": 9004,
		"protocol": "mqttwss",
		"enabled": true,
		"tls": {
			"serverCertificateFilename": "./web/fccert.pem"
		}
	}
    7. Copy the contents of the config/replication/ctagent.cfg file in the Source server (a prebuilt example file that enables manual replication mode) and paste it over the config/ctagent.cfg file in the Target server to enable manual replication quickly. This is currently the only replication mode supported. Make sure to remove the lines containing agent2 and agent3 from the config/replication/ctagent.json file.
    8. In <faircom>\target\config\replication\ctreplagent.cfg, change Target:
      1. target_server FAIRCOMS@localhost
source_server FAIRCOMS@SourceIP
      2. to:
      3. target_server FAIRCOMT@localhost
target_nodeid 10.0.0.2
source_server FAIRCOMS@localhost
source_nodeid 10.0.0.1
        Note the target_nodeid and source_nodeid are needed for parallel apply support, which is on by default. 
  5. In <faircom>\target\config\replication\filter.xml, configure Target to be sure you have selected files to replicate. For example, set to <file status="include">.\ctreeSQL.dbs\admin*.dat</file> to get all admin*.dat files in data\ctreeSQL.dbs folder. Note that if you're using synchronous replication, you must add the option syncagent yes to the ctreplagent.cfg replication agent configuration file.
  6. If you have changed the "ADMIN" user ID password, or if authentication information has changed, you will need to generate new .set files (see ctcmdset - Configuration File Encoding Utility).
  1. Start the Source server.
  2. Start the Target server. 
  3. Check for the Plugin start message in the Target <faircom>\target\data\CTSTATUS.FCS log file. Plugin ctagent successfully started. Time to start=2.1 sec
  4. Check the replication log, which is referenced in the following keyword in <faircom>\target\config\replication\ctreplagent1.cfg. It should present messages saying the replication agent was started and was able to connect to both source and target servers.
    1. REPLAGENT1: Main: INFO: ** Starting replication agent logging for process 15436

Logread: INFO: Connected to data target 'FAIRCOMT@localhost'.

Logread: INFO: Connected to data source 'FAIRCOMT'.
  5. You are now ready to connect an application to the Source server and create some files and data. One quick way to do this is use the SQL Commands tab in the FairCom Control Center app to paste the contents of the <faircom>\drivers\sql.cli\tutorials\iSQL_Tutorial4.sql Script as shown here. Type https://127.0.0.1:8443/ in a browser (we recommend the Chrome browser):
  6. Scroll the script down to the bottom and delete these DROP TABLE statements:
    1. DROP TABLE ordritem;

DROP TABLE custordr;

DROP TABLE itemmast;

DROP	TABLE custmast;

COMMIT WORK;
  7. Now press the Run button. This will create 4 tables and will insert 4 records. You can see the tables by selecting Tables from the Data menu. 
  1. Click on the custmast table to view the records: 

If replication is working as expected, the file create operation on the Source server will be replicated on the Target server. You can confirm this happened by listing the <faircom>\target\data\ctreeSQL.dbs folder. You should see something like the following when logging into the FairCom Control Center of the Target server instance here https://localhost:8444:

If the file create operation was not replicated on the Target server, you can open CTSTATUS.FCS to troubleshoot the issue. Once the issue has been resolved, you can restart the replication agent by calling ctadmn or by using the manageService action.

basic copycat

Was this article helpful?

Give feedback about this article

Related Articles