Activating Q Replication by using the REST APIs

You need to activate the Q Replication process on both the source and target databases to begin replicating data.

Before you begin

Replication is activated on the cluster host for both the source and target databases. Ensure that you collect the following information before you run any commands:
  • The instance ID of your Db2 instance.
  • The basic authorization token of the source on the cluster host.1
  • The name of the host on which you want to activate Q Replication.
  • The username and password of the source database.
1 You need to create a basic authorization token to run a cURL request. To create your token, run this command:
echo <source_db_username>:<source_db_password> | base64

About this task

An activated Q Replication system manages replication sets and the target systems. When you activate Q Replication:

  • Db2® Warehouse SaaS settings are changed to provide necessary replication information in the database recovery logs.
  • Message queues and other IBM® MQ objects are enabled as the data transport method between the source and target databases.
  • Metadata tables are created to store your preferences and track replicated data.
  • The queue manager, capture process, and Q Replication REST server are started.

Procedure

Enable Q Replication on the host system: 
curl --insecure -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 
'Authorization: Basic <your_authorization_token>' -d '{ "dbUsername": "<source_db_username>", "dbPassword": 
"<source_db_password>" }' 'https://<source_hostname>:9444/dr/v2/source/<source_hostname>/50001/BLUDB?asnmon=n'
This API call returns a job number (id): 
{
  "id": <job_number>,
  "url": "https://<source_hostname>:9444/dr/v1/target/progress/<job_number>"
}

You can check the progress repeatedly using the URL displayed in the Response by using the job number from the API call response: 

curl --insecure -X GET --header 'Accept: application/json' --header 'Authorization: Basic <your_authorization_token>' 
'https://<source_hostname>:9444//dr/v1/source/progress/<job_number>'

Results

The activation process can return any of the following HTTP status codes:
HTTP Status Code Reason Response Model
202 Background job to activate replication is started The user request returns a job (id) and URL as the API call starts (sample value): 

{
  "id": 1,
  "url": "string"
}
200 The job status check on replication activation API is successful Look for executionState=COMPLETED and overallJobResult=PASS return values in the response body.
4xx Client request error The user request was not fulfilled due to malformed request syntax or other client issues:
{
  "errorCode": "string",
  "errorMessage": "string",
  "errorResolution": "string"
}
5xx Server error The user request appeared valid, but was not fulfilled due to an issue with the server:
{
  "errorCode": "string",
  "errorMessage": "string",
  "errorResolution": "string"
}

The replication activation is complete when a response message that contains executionState=COMPLETED and overallJobResult=PASS is returned. You can proceed to trust the target database and exchange Db2 Transport Layer Security (TLS) certificates. Until these values are returned, examine the error code, message, and resolution in the response.

Example

The following example shows the command syntax for activating Q Replication on the host dr.source1.ibm.com:
curl --insecure -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' 
--header 'Authorization: Basic ZHNhZG06MDNRVWlMczFhcmoxb3ky' -d '{ "dbUsername": "myuser1", "dbPassword": "mypass1" }' 
'https://dr.source1.ibm.com:31023/dr/v2/source/dr.source1.ibm.com/32621/BLUDB?asnmon=n'
The following example shows the command syntax for returning the status of the Q Replication activation process by using the returned job number, 1:
curl --insecure -X GET --header 'Accept: application/json' --header 'Authorization: Basic ZHNhZG06aFRjT3dTTjR1RFo0N1Ew' 
'https://dr-source1.ibm.com:31023/dr/v1/source/progress/1'

What to do next

Configuring targets and replication sets with the Db2 Q Replication REST API