Distributed Availability Groups - Failover

Service:: SQL Database

API Version:: 2025-01-01

Performs requested failover type in this distributed availability group.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/managedInstances/{managedInstanceName}/distributedAvailabilityGroups/{distributedAvailabilityGroupName}/failover?api-version=2025-01-01

URI Parameters

Name	In	Required	Type	Description
distributedAvailabilityGroupName	path	True	string	The distributed availability group name.
managedInstanceName	path	True	string	The name of the managed instance.
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string (uuid)	The ID of the target subscription. The value must be an UUID.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
failoverType	True	FailoverType	The failover type, can be ForcedAllowDataLoss or Planned.

Responses

Name	Type	Description
200 OK	DistributedAvailabilityGroup	Azure operation completed successfully.
202 Accepted		Resource operation accepted. Headers Location: string Retry-After: integer
Other Status Codes	ErrorResponse	An unexpected error response.

Name

Type

Description

200 OK

DistributedAvailabilityGroup

Azure operation completed successfully.

202 Accepted

Resource operation accepted.

Headers

Location: string
Retry-After: integer

Other Status Codes

ErrorResponse

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Failover a distributed availability group.

Sample request

HTTP

POST https://management.azure.com/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Sql/managedInstances/testcl/distributedAvailabilityGroups/dag/failover?api-version=2025-01-01

{
  "failoverType": "ForcedAllowDataLoss"
}

Sample response

Status code:: 200

{
  "name": "dag",
  "type": "Microsoft.Sql/managedInstances/distributedAvailabilityGroups",
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Sql/managedInstances/testcl/distributedAvailabilityGroups/dag",
  "properties": {
    "databases": [
      {
        "connectedState": "CONNECTED",
        "databaseName": "testdb",
        "instanceRedoReplicationLagSeconds": 1,
        "instanceReplicaId": "4713ed91-1e8c-497d-9bd4-d8a3935ae49a",
        "instanceSendReplicationLagSeconds": 1,
        "lastBackupLsn": "71000009405700001",
        "lastBackupTime": "2023-08-01T00:00:00Z",
        "lastCommitLsn": "71000009407900004",
        "lastCommitTime": "2023-08-01T00:00:00Z",
        "lastHardenedLsn": "71000009408100001",
        "lastHardenedTime": "2023-08-01T00:00:00Z",
        "lastReceivedLsn": "71000009407900001",
        "lastReceivedTime": "2023-08-01T00:00:00Z",
        "partnerReplicaId": "8ffa9723-a1ec-4323-b929-c4aedee3894b",
        "replicaState": "Catchup",
        "synchronizationHealth": "HEALTHY"
      }
    ],
    "distributedAvailabilityGroupId": "c856cff5-a6fe-418e-8894-17799cc20f5d",
    "distributedAvailabilityGroupName": "dag",
    "failoverMode": "None",
    "instanceAvailabilityGroupName": "testcl",
    "instanceLinkRole": "Primary",
    "partnerAvailabilityGroupName": "BoxLocalAg1",
    "partnerEndpoint": "TCP://SERVER:7022",
    "partnerLinkRole": "Secondary",
    "replicationMode": "Async",
    "seedingMode": "Automatic"
  }
}

Status code:: 202

Location: https://management.azure.com/subscriptions/f2669dff-5f08-45dd-b857-b2a60b72cdc9/providers/Microsoft.Sql/locations/westus/distributedAvailabilityGroupsOperationResults/00000000-1111-2222-3333-444444444444?api-version=2023-08-01-preview

Definitions

Name	Description
CertificateInfo	Certificate information
createdByType	The type of identity that created the resource.
DistributedAvailabilityGroup	Distributed availability group between box and Sql Managed Instance.
DistributedAvailabilityGroupDatabase	Database specific information
DistributedAvailabilityGroupsFailoverRequest	Distributed availability group failover.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
FailoverModeType	The link failover mode - can be Manual if intended to be used for two-way failover with a supported SQL Server, or None for one-way failover to Azure.
FailoverType	The failover type, can be ForcedAllowDataLoss or Planned.
LinkRole	SQL server side link role
ReplicaConnectedState	Link connected state
ReplicaSynchronizationHealth	Link health state
ReplicationModeType	Replication mode of the link
SeedingModeType	Database seeding mode – can be Automatic (default), or Manual for supported scenarios.
systemData	Metadata pertaining to creation and last modification of the resource.

CertificateInfo

Object

Certificate information

Name	Type	Description
certificateName	string	The certificate name
expiryDate	string (date-time)	The certificate expiry date

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
User
Application
ManagedIdentity
Key

DistributedAvailabilityGroup

Object

Distributed availability group between box and Sql Managed Instance.

Name	Type	Description
id	string (arm-id)	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
name	string	The name of the resource
properties.databases	DistributedAvailabilityGroupDatabase[]	Databases in the distributed availability group
properties.distributedAvailabilityGroupId	string (uuid)	ID of the distributed availability group
properties.distributedAvailabilityGroupName	string	Name of the distributed availability group
properties.failoverMode	FailoverModeType	The link failover mode - can be Manual if intended to be used for two-way failover with a supported SQL Server, or None for one-way failover to Azure.
properties.instanceAvailabilityGroupName	string	Managed instance side availability group name
properties.instanceLinkRole	LinkRole	Managed instance side link role
properties.partnerAvailabilityGroupName	string	SQL server side availability group name
properties.partnerEndpoint	string	SQL server side endpoint - IP or DNS resolvable name
properties.partnerLinkRole	LinkRole	SQL server side link role
properties.replicationMode	ReplicationModeType	Replication mode of the link
properties.seedingMode	SeedingModeType	Database seeding mode – can be Automatic (default), or Manual for supported scenarios.
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

DistributedAvailabilityGroupDatabase

Object

Database specific information

Name	Type	Description
connectedState	ReplicaConnectedState	Link connected state
databaseName	string	The name of the database in link
instanceRedoReplicationLagSeconds	integer (int32)	Redo lag when Managed Instance link side is primary
instanceReplicaId	string (uuid)	Managed instance replica id
instanceSendReplicationLagSeconds	integer (int32)	Replication lag when Managed Instance link side is primary
lastBackupLsn	string	Last backup LSN
lastBackupTime	string (date-time)	Last backup LSN time
lastCommitLsn	string	Last commit LSN
lastCommitTime	string (date-time)	Last commit LSN time
lastHardenedLsn	string	Last hardened LSN
lastHardenedTime	string (date-time)	Last hardened LSN time
lastReceivedLsn	string	Last received LSN
lastReceivedTime	string (date-time)	Last received LSN time
lastSentLsn	string	Last sent LSN
lastSentTime	string (date-time)	Last sent LSN time
mostRecentLinkError	string	The most recent link connection error description
partnerAuthCertValidity	CertificateInfo	SQL server certificate validity
partnerReplicaId	string (uuid)	SQL server replica id
replicaState	string	Current link state
seedingProgress	string	Seeding progress
synchronizationHealth	ReplicaSynchronizationHealth	Link health state

DistributedAvailabilityGroupsFailoverRequest

Object

Distributed availability group failover.

Name	Type	Description
failoverType	FailoverType	The failover type, can be ForcedAllowDataLoss or Planned.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

Error response

Name	Type	Description
error	ErrorDetail	The error object.

FailoverModeType

Enumeration

The link failover mode - can be Manual if intended to be used for two-way failover with a supported SQL Server, or None for one-way failover to Azure.

Value	Description
None	None
Manual	Manual

FailoverType

Enumeration

The failover type, can be ForcedAllowDataLoss or Planned.

Value	Description
ForcedAllowDataLoss	ForcedAllowDataLoss
Planned	Planned

LinkRole

Enumeration

SQL server side link role

Value	Description
Primary	Primary
Secondary	Secondary

ReplicaConnectedState

Enumeration

Link connected state

Value	Description
DISCONNECTED	DISCONNECTED
CONNECTED	CONNECTED

ReplicaSynchronizationHealth

Enumeration

Link health state

Value	Description
NOT_HEALTHY	NOT_HEALTHY
PARTIALLY_HEALTHY	PARTIALLY_HEALTHY
HEALTHY	HEALTHY

ReplicationModeType

Enumeration

Replication mode of the link

Value	Description
Async	Async
Sync	Sync

SeedingModeType

Enumeration

Database seeding mode – can be Automatic (default), or Manual for supported scenarios.

Value	Description
Automatic	Automatic
Manual	Manual

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string (date-time)	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string (date-time)	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

Share via

Distributed Availability Groups - Failover

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Failover a distributed availability group.

Sample request

Sample response

Definitions

CertificateInfo

createdByType

DistributedAvailabilityGroup

DistributedAvailabilityGroupDatabase

DistributedAvailabilityGroupsFailoverRequest

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

FailoverModeType

FailoverType

LinkRole

ReplicaConnectedState

ReplicaSynchronizationHealth

ReplicationModeType

SeedingModeType

systemData