API Actions: PromoteDbReplicaToPrimary

Request Syntax:

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",
        "parallelTablesLimit": 5 -- 13.32 and above: Default = 1; limits number of concurrently processed tables during running of AnalyzeReport to detect discrepancies, applicable with "ignoreDbDiscrepancies" : "false" only.
	
        "cancelRunningCtProcess"  : "false",
        "turnOffDataReplication": "false" -- 12.348 and above: default = False; a value of True requires ignoreInaccessibleSourceConnection=true, ignoreDbDiscrepancies=true, cancelRunningCtProcess=true
        "enableConstraintsWithCheck" : "true" -- 12.283 and above 
}

Request Parameters

Parameter	Description	Required
ReplicationId	The ReplicationID returned in the CreateReplication response.	Yes
ReplicationId	Type: String Default: None	Yes
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
IgnoreInaccessibleSourceConnection	Type: String Default: False Valid value: true/ false	Yes
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
IgnoreDbDiscrepancies	Type: String Default: False Valid value: true/ false	Yes
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
CancelRunningCtProcess	Type: String Default: False Valid value: true/ false	Yes
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
EnableConstraintsWithCheck (12.283 and above)	Type: String Default: True Valid value: true/ false	No

Note:
In version 12.348 and above, the API call allows DataReplication for primary and all secondary jobs to be turned off as part of the /api/PromoteDbReplicaToPrimary call, by requesting turnOffDataReplication=true. This scenario is applicable generally for non-planned fail-over with lost primary connection.
Important: If PromoteToPrimary fails, DataReplication will remain turned off. Need to call /AlterReplication if need to turn DataReplication back on, for the primary and all secondary jobs.

In versions prior to 12.283, DataReplication was being implicitly turned off if requirements to initiate the promote to primary process were being satisfied:

1- Destination is accessible
2- (Source is accessible) or (Source is inaccessible but <IgnoreInaccessibleSourceConnection>true</IgnoreInaccessibleSourceConnection>
3- (<IgnoreDbDiscrepancies>true</IgnoreDbDiscrepancies>) or (<IgnoreDbDiscrepancies>false</IgnoreDbDiscrepancies> and No Discrepancies found)

In 12.248 and after, the parameter turnOffDataReplication was introduced, which for non-planned fail-over allows data replication for primary and all econdary jobs to be explicitly turned off as part of the promote to primary API call.

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:

JSON

HTTP/1.1 200
status: 200

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

Response Parameters

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:

JSON

HTTP/1.1 400
status: 400

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

JSON

HTTP/1.1 400
status: 400

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

JSON

HTTP/1.1 400
status: 400

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