Initializing the replication target on the replication source

Initializing the replication target on the replication source means to make the target visible to the source for replication.

Before you begin

This task is done on the cluster host for the replication source. Ensure that you collect the following information before you run the API call:

  • Your Db2® instance ID
  • The basic authorization token of the source on the cluster host.1
  • The host name of the replication target database.
  • The external port number of the replication target database.2
  • The username and password of the replication target database.
You need this information to run the needed Replication REST API calls.
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
2 You can retrieve the external port number of the replication target database by running the following command:
oc get svc | grep <db2_instance_id> | grep db2u-engn-svc | grep 50001 | sed 's/.*50001://' | sed 's/\/TCP.*//')

About this task

While the initializing of the replication target changes the configuration of the replication source, a number of changes also occur at the target:

  • The Db2 settings are changed to provide the necessary replication information to the target database.
  • The Apply message queue manager is configured on the target system.
  • The Capture queue manage utility on the source is configured to communicate with the target system.
  • The Apply metadata tables are created on the target database.
  • The queue manager, apply process, and Replication REST server are started.

Procedure

  1. Enable replication at the replication target by using the basic authorization token of the replication source: 
    curl --insecure -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic <your_authorization_token>' -d '{ "dbUsername": "<target_db_username>", "dbPassword": "<target_db_password>" }' 
'https://<source_hostname>:<source_rest_port>/dr/v2/target/<target_hostname>/<target_db_port>/BLUDB?asnmon=n'

    This API call returns a job number (id).

    {
  "id": <job_number>,
  "url": "https://<source_hostname>:<source_rest_external_port>/dr/v1/target/progress/<job_number>"
}
  2. Include the job number in the following API call to check the progress of the replication enablement at the target: 
    curl --insecure -X GET --header 'Accept: application/json' --header 'Authorization: Basic <your_authorization_token>' 
'https://<source_hostname>:<source_rest_port>/dr/v1/target/progress/<job_number>'

Results

The enablement of replication at the target is complete when a response message that contains executionState=COMPLETED and overallJobResult=PASS is returned. Until these values are returned, examine the error code, message, and resolution in the response.
The following table lists the possible HTTP status codes and response messages for the replication target enablement API calls. It also includes sample code to show the response syntax.
HTTP Status Code Reason Response Model
202 Target initialization started The user request returns a job (id) and URL as the API call starts (sample value):

  "id": 1,
  "url": "https://dr-source1.ibm.com:31023/dr/v1/replicationset/progress/1"
}
200 Status check for target initialization 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"
}

Example

The following example shows the command syntax for enabling replication at the target database. See step 1 :
curl --insecure -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic ZHNhZG06aFRjT3dTTjR1RFo0N1Ew' -d '{ "dbUsername": "myuser1", "dbPassword": "mypass1" }' 
'https://dr.source1.ibm.com:31023/dr/v2/target/dr.target2.ibm.com/32621/BLUDB?asnmon=n'
The following example shows the command syntax for checking the status of the replication enablement at the target by using the generated job number, 1. See step 2:
curl --insecure -X GET --header 'Accept: application/json' --header 'Authorization: Basic ZHNhZG06aFRjT3dTTjR1RFo0N1Ew' 
'https://api.dr-source1.ibm.com:30674/dr/v1/target/progress/1'

What to do next

Create a replication set.