API Actions: PromoteToPrimary

API Actions: PromoteDbReplicaToPrimary

 

Request Syntax:

XML

POST /api/PromoteDbReplicaToPrimary HTTP/1.1
Host: use.your.host.name:82
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Content-Type: application/xml
X-Amz-Date: 20171115T202130Z
Authorization: AWS4-HMAC-SHA256 Credential= UQOPWUVNBALABCABCABC/20171115/us-east-1/cloudbasic/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-content-sha256;x-amz-date, Signature=995374189c189e8e68ed3de82c1764ca11971711fb5179eeab2b19edd883dd74
 
<?xml version="1.0" encoding="utf-8"?>
<PromoteDbReplicaToPrimaryRequest>
	<ReplicationId>998acaec-9211-4dac-b90b-196fd1d17993</ReplicationId>
	<IgnoreInaccessibleSourceConnection>false</IgnoreInaccessibleSourceConnection>
	<IgnoreDbDiscrepancies>false</IgnoreDbDiscrepancies>
	<CancelRunningCtProcess>false</CancelRunningCtProcess>
        <EnableConstraintsWithCheck>true</EnableConstraintsWithCheck> <!-- 12.283 and above --> 
</PromoteDbReplicaToPrimaryRequest>

JSON

POST /api/PromoteDbReplicaToPrimary HTTP/1.1
Host: use.your.host.name:82
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Content-Type: application/json
X-Amz-Date: 20171115T202130Z
Authorization: AWS4-HMAC-SHA256 Credential= UQOPWUVNBALABCABCABC/20171115/us-east-1/cloudbasic/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-content-sha256;x-amz-date, Signature=995374189c189e8e68ed3de82c1764ca11971711fb5179eeab2b19edd883dd74
 
{
	"replicationId": "998acaec-9211-4dac-b90b-196fd1d17993",
	"IgnoreInaccessibleSourceConnection" : "false",
	"ignoreDbDiscrepancies" : "false",
	"cancelRunningCtProcess"  : "false",
        "enableConstraintsWithCheck" : "true" -- 12.283 and above 
}

 

Request Parameters

Parameter Description Required
ReplicationId The ReplicationID returned in the CreateReplication response. Yes
Type: String
Default: None
IgnoreInaccessibleSourceConnection Set this tag True to promote the database to primary if connection to source is lost. It is generally applicable to unplanned DR fail-over cases. Yes
Type: String
Default: False
Valid value: true/ false
IgnoreDbDiscrepancies Set this tag True to promote replica to primary even if discrepancies are found in 1 or more tables, or source DB is inaccessible.
Note:
If the tag is not included, or set False, an error will be returned if discrepancies are found in 1 or more tables, or source database is inaccessible. To retrieve discrepancy report details, call /AnalyzeReplication method.		 Yes
Type: String
Default: False
Valid value: true/ false
CancelRunningCtProcess Setting this tag to True will force the cancellation of the Continuous Tracking process. This option is useful in situations where the primary database is no longer available and allowing the Change Tracking process to finish is not needed. Yes
Type: String
Default: False
Valid value: true/ false
EnableConstraintsWithCheck
(12.283 and above)
 By default, the promote process enabled constraints/Foreign Keys with CHECK (validating existing data referential integrity constraints). Value of False (NOCHECK) will enable constraints without validation of existing data referential integrity.
For databases with substantial size (1TB and above) with large number of  constraints, the promote to primary process could take long time.I.e. for a 2TB database with 2000 constraints and large tables involved in parent-detail relationships with Foreign Key constraints enforcing the relationships, the process could potentially take more than 3 hours.In the case of planned cut-over, in the above scenario, it is recommended to first test replica data referential integrity under defaults, then during the final cut-over to go with NOCHECK to substantially reduce the cut-over time.

EnableConstraintsWithCheck=False must be used with caution.

 No
Type: String
Default: True
Valid value: true/ false

Note:
In this version, DataReplication will be turned off first, and then attempt to promote the respective DB to primary. If there is a running change tracking process, this will result into an error. Keep calling /PromoteToPrimary until the running process completes at which point promotion to primary will be initiated. In cases where the primary database is no longer accessible, instead of waiting for the running change tracking process to finish, a forceful cancellation requested via the CancelRunningCtProcess tag.

Important: Even if PromoteToPrimary fails, DataReplication will remain turned off. Need to call /AlterRpelication to turn DataReplication back on.

 

Request Headers

This implementation uses only request headers that are common to all operations. For more information please see the section Common Request Headers

 

Response Syntax:

XML

HTTP/1.1 200
status: 200
 
<?xml version="1.0" encoding="utf-8"?>
<PromoteDbReplicaToPrimaryResponse>
	<InaccessibleSourceConnection>true</InaccessibleSourceConnection>
	<DiscrepanciesFound>true</DiscrepanciesFound>
	<RunningProcessCancelled>true</RunningProcessCancelled>
	<Status>Running</Status>
</PromoteDbReplicaToPrimaryResponse>

JSON

HTTP/1.1 200
status: 200

{
	"inaccessibleSourceConnection": false,
	"discrepanciesFound": true,
	"runningProcessCanceled": true,
	"status": "Running"
}

 

Response Parameters

IMPORTANT:
[Data Replication] is turned off if requirements to initiate the promote to primary process are satisfied (see below for details). If the promote to primary process fails and need to un-promote, call api/AlterReplication with tag <DataReplication>true</DataReplication> to back enable it.
[Data Replication] will be disabled prior to initiating the Promote to Primary process if:

    • 1- Destination is accessible

and

    • 2- (Source is accessible) or (Source is inaccessible but <IgnoreInaccessibleSourceConnection>true</IgnoreInaccessibleSourceConnection>)

and

  • 3- (<IgnoreDbDiscrepancies>true</IgnoreDbDiscrepancies>) or (<IgnoreDbDiscrepancies>false</IgnoreDbDiscrepancies> and No Discrepancies found)

 

Parameter Description Optional
InaccessibleSourceConnection It is True when api/PromoteDbReplicaToPrimary was requested with <IgnoreInaccessibleSourceConnection>true</IgnoreInaccessibleSourceConnection> and source DB connection was not accessible.
Below tag is returned ONLY if PromoteDbReplicaToPrimary is requested with <IgnoreDbDiscrepancies>false</IgnoreDbDiscrepancies>. In that case Analyze for discrepancies is not performed and discrepancy status is unknown.		 Yes
DiscrepanciesFound It is True when discrepancies in 1 or more tables were found.
Note:
If PromoteToPrimary is requested with <IgnoreDbDiscrepancies>true</IgnoreDbDiscrepancies>, the replica DB will be promoted to primary even if discrepancies in 1 or more tables are found or source DB is inaccessible. To retrieve discrepancy report details call /AnalyzeReport (applicable if source DB is accessible).		 No
RunningCtProcessCancelled It is True when a running Change Tracking process had to be forcefully canceled on this server or a remote cluster server. See tag CancelRunningCtProcess in api/PromoteToPrimary method. Yes
Status The current status of the PromoteToPrimary process. Possible values include:

  • Running
  • Failed
  • Success

Note:
Even if the asynchronous process completes instantly with status Failed or Success, logs will not be returned. Logs can be requested via api/PromoteToPrimaryStatus method.

 No

 

Error Response Syntax:

XML

HTTP/1.1 400
status: 400
 
<?xml version="1.0" encoding="utf-8"?>
<ErrorResponse> 
	<RequestId>request-id</RequestId> 
	<Errors> 
		<Error> Inaccessible source DB connection </Error> 
		<Error> Inaccessible destination DB connection </Error> 
	</Errors> 
</ErrorResponse>

JSON

HTTP/1.1 400
status: 400

{
   "errors": [
       "Inaccessible source DB connection",
       "Inaccessible destination DB connection"
	],
	"requestId": 26
}

XML

HTTP/1.1 400
status: 400
 
<?xml version="1.0" encoding="utf-8"?>
<ErrorResponse> 
	<RequestId>request-id</RequestId> 
	<Errors> 
		<Error> Change Tracking process is still running </Error> 
	</Errors> 
</ErrorResponse>

JSON

HTTP/1.1 400
status: 400

{
   "errors": [
       "Change Tracking process is still running"
	],
	"requestId": 21
}

XML

HTTP/1.1 400
status: 400
 
<?xml version="1.0" encoding="utf-8"?>
<ErrorResponse> 
	<RequestId>request-id</RequestId> 
	<Errors> 
		<Error> Discrepancies found. To ignore discrepancies and promote call /PromoteDbReplicaToPrimary with tag IgnoreDbDiscrepancies=true </Error> 
	</Errors> 
</ErrorResponse>

JSON

HTTP/1.1 400
status: 400

{
   "errors": [
       "Discrepancies found. To ignore discrepancies and promote call /PromoteDbReplicaToPrimary with tag IgnoreDbDiscrepancies=true"
	],
	"requestId": 21
}