Failover Groups - Update

Updates a failover group.

PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/failoverGroups/{failoverGroupName}?api-version=2020-11-01-preview

URI Parameters

Name In Required Type Description
failoverGroupName
path True
  • string

The name of the failover group.

resourceGroupName
path True
  • string

The name of the resource group that contains the resource. You can obtain this value from the Azure Resource Manager API or the portal.

serverName
path True
  • string

The name of the server containing the failover group.

subscriptionId
path True
  • string

The subscription ID that identifies an Azure subscription.

api-version
query True
  • string

The API version to use for the request.

Request Body

Name Type Description
properties.databases
  • string[]

List of databases in the failover group.

properties.readOnlyEndpoint

Read-only endpoint of the failover group instance.

properties.readWriteEndpoint

Read-write endpoint of the failover group instance.

tags
  • object

Resource tags.

Responses

Name Type Description
200 OK

Successfully updated the failover group.

202 Accepted

Accepted

Other Status Codes

*** Error Responses: ***

  • 400 FailoverGroupCreateOrUpdateRequestInvalidDatabases - The provided databases IDs are not properly constructed database resource IDs. For the example of proper formatting see https://docs.microsoft.com/en-us/rest/api/sql/failovergroups/createorupdate

  • 400 FailoverGroupCreateOrUpdateRequestInvalidPartner - The given partners field in create or update failover group request body is empty or invalid. Please provide a valid value of this field. For examples of properly formatted requests seeĀ  https://docs.microsoft.com/en-us/rest/api/sql/failovergroups/createorupdate

  • 400 FailoverGroupCreateOrUpdateRequestDuplicatePartner - One or more of the provided partner servers are already part of the failover group. Please make sure the primary server and all of the given partner servers are unique.

  • 400 FailoverGroupCreateOrUpdateRequestInvalidDatabaseServer - One or more of the provided databases do not exist on the primary server of the failover group. Please make sure that all the databases exist on the primary server.

  • 400 FailoverGroupCreateOrUpdateRequestUnsupportedPartnerCount - Only one partner server for Failover Group is supported. Please modify your request accordingly. For examples of valid requests see https://docs.microsoft.com/en-us/rest/api/sql/failovergroups/createorupdate

  • 400 FailoverGroupCreateOrUpdateRequestInvalidReadWriteEndpoint - The readWriteEndpoint field is required for create or update requests.

  • 400 FailoverGroupCreateOrUpdateRequestInvalid - The create or update failover group request body is empty or invalid.

  • 400 FailoverGroupUpdateOrDeleteRequestOnSecondary - Modifications to the failover group are not allowed on a secondary server. Execute the request on the primary server.

  • 400 FailoverGroupCreateOrUpdateRequestNegativeGracePeriodValues - Grace period value for the read-write endpoint must be non-negative.

  • 400 FailoverGroupCreateOrUpdateRequestInvalidReadWriteEndpointFields - The property failoverWithDataLossGracePeriodMinutes must be provided when failover policy Automatic is selected for the read-write endpoint.

  • 400 FailoverGroupCreateOrUpdateRequestInvalidReadWriteFailoverPolicy - The failoverPolicy field for the read-write endpoint is required for create or update requests.

  • 400 FailoverGroupCreateOrUpdateRequestInvalidReadWriteEndpointFieldsForManualPolicy - Grace period value should not be provided when failover policy Manual is selected for the read-write endpoint. Please remove it from request.

  • 400 FailoverGroupCreateOrUpdateRequestReadOnlyPropertyModified - The create or update failover group request body should not modify the read-only property '{0}'.

  • 400 FailoverGroupFailoverRequestOnPrimary - The failover request should be initiated on the secondary server of failover group.

  • 400 FailoverGroupPartnerServerFromDifferentSubscription - Primary server and the partner servers of failover group are from different subscriptions. Cross subscription for servers of failover group is not allowed.

  • 400 InvalidAddSecondaryPermission - User does not have sufficient permission to add secondary on the specified server.

  • 400 InvalidSku - The user specified an invalid sku.

  • 400 ServerNotFound - The requested server was not found.

  • 400 FeatureDisabledOnSelectedEdition - User attempted to use a feature which is disabled on current database edition.

  • 400 TokenTooLong - The provided token is too long.

  • 400 InvalidTargetSubregion - The target server of a non-readable secondary is not in a DR paired Azure region.

  • 400 PartnerServerNotCompatible - The user is attempting to copy a database from a SAWA V1 server to a Sterling server or vice versa.

  • 400 IncorrectReplicationLinkState - The operation expects the database to be in an expected state on the replication link.

  • 400 ResourcePoolNotFound - Specified elastic pool does not exist in the specified logical server.

  • 400 AzureKeyVaultInvalidExpirationDate - The operation could not be completed because the Azure Key Vault key expiration date is invalid.

  • 400 SecurityAzureKeyVaultUrlNullOrEmpty - The operation could not be completed because the Azure Key Vault Uri is null or empty.

  • 400 AzureKeyVaultInvalidUri - An invalid response from Azure Key Vault. Please use a valid Azure Key Vault URI.

  • 400 SecurityAzureKeyVaultInvalidKeyName - The operation could not be completed because of an invalid Server Key name.

  • 400 PlannedFailoverTimedOutForDatabase - User invoked planned failover, it timed out, and a specific database appears to be to blame.

  • 400 PlannedFailoverTimedOut - User invoked planned failover, and it timed out while trying to contact the partner management service.

  • 400 AzureKeyVaultMalformedVaultUri - The provided Key Vault uri is not valid.

  • 400 CannotUseReservedDatabaseName - Cannot use reserved database name in this operation.

  • 400 InvalidFailoverGroupRegion - Servers specified in a Failover Group need to reside in different regions to provide isolation.

  • 400 FailoverGroupDoesNotExist - Failover group does not exist on a server.

  • 400 FailoverGroupNotSecondary - Failover cannot be initiated from the primary server in a Failover Group.

  • 400 InvalidServerName - Invalid server name specified.

  • 400 DatabaseInFailoverGroupNotPrimary - GeoDR link for the database already exists, but its role is not 'Primary' or it is not continuous copy link.

  • 400 SecurityAdalPrincipalCertExpiredError - The operation could not be completed because the Azure Key Vault principal certificate has expired.

  • 400 UnableToCreateFailoverGroupDueToTableAuditing - Failover Group cannot be created for server that has table auditing turned on.

  • 400 InvalidIdentifier - The identifier contains NULL or an invalid unicode character.

  • 400 UnableToAddDbWithTableAuditingToFailoverGroup - Database with Table Auditing enabled will not be accessible through Failover Group endpoint.

  • 400 SecurityInvalidAzureKeyVaultRecoveryLevel - The provided Key Vault uri is not valid.

  • 400 KeyMaterialNotFoundOnRemoteServer - Remote server does not have access to key material used as a TDE protector.

  • 400 LimitOfFailoverGroupsPerServerExceeded - Creating new Failover Group will exceed the allowed number of Failover Groups per server.

  • 400 AzureKeyVaultMismatchError - Unexpected Key Vault region found in the http response.

  • 400 AzureKeyVaultRsaKeyNotSupported - The provided key vault uses unsupported RSA Key Size or Key Type. The supported RSA key size is 2048 or 3072 and Key Type is RSA or RSA-HSM.

  • 400 GeoReplicationDatabaseNotSecondary - The operation expects the database to be a replication target.

  • 400 GeoReplicaLimitReached - The per-replica replication limit was reached.

  • 400 FailoverGroupWithVirtualNetworkRulesNotSupported - Failover Groups configured with an automatic failover policy are currently not supported on servers configured with virtual network firewall rules. Please configure the failover group with manual failover policy.

  • 400 UnableToResolveRemoteServer - The remote partner server name could not be resolved due to an invalid server name or DNS connectivity issues.

  • 400 RemoteDatabaseCopyPermission - User does not have sufficient permission to create a database copy on the specified server.

  • 400 SecurityAzureKeyVaultGeoChainError - Creating secondary of secondary (a process known as chaining) is not supported when enabling Transparent Data Encryption using Azure Key Vault (BYOK).

  • 400 FailoverGroupCreateOrUpdatePartiallySucceeded - Some databases could not be added or removed.

  • 401 AzureKeyVaultKeyDisabled - The operation could not be completed on the server because the Azure Key Vault key is disabled.

  • 401 AzureKeyVaultNoServerIdentity - The server identity is not correctly configured.

  • 401 AzureKeyVaultMissingPermissions - The server is missing required permissions on the Azure Key Vault.

  • 401 AdalGenericError - The operation could not be completed because an Azure Active Directory error was encountered.

  • 401 AdalServicePrincipalNotFound - The operation could not be completed because an Azure Active Directory library Service Principal not found error was encountered.

  • 404 OperationIdNotFound - The operation with Id does not exist.

  • 404 ResourceNotFound - The requested resource was not found.

  • 404 OperationIdNotFound - The operation with Id does not exist.

  • 404 ServerNotInSubscriptionResourceGroup - Specified server does not exist in the specified resource group and subscription.

  • 404 ServerNotInSubscription - Specified server does not exist on the specified subscription.

  • 404 SourceDatabaseNotFound - The source database does not exist.

  • 405 UnsupportedReplicationOperation - An unsupported replication operation was initiated on the database.

  • 409 OperationCancelled - The operation has been cancelled by user.

  • 409 OperationInterrupted - The operation on the resource could not be completed because it was interrupted by another operation on the same resource.

  • 409 ConflictingServerOperation - An operation is currently in progress for the server.

  • 409 SubscriptionDisabled - Subscription is disabled.

  • 409 ConflictingSystemOperationInProgress - A system maintenance operation is in progress on the database and further operations need to wait until it is completed.

  • 409 GeoReplicationCannotBecomePrimaryDuringUndo - User attempted to failover or force-terminate a geo-link while the secondary is in a state where it may not be physically consistent and so cannot enter the primary role.

  • 409 ServerKeyNameAlreadyExists - The server key already exists on the server.

  • 409 ServerKeyUriAlreadyExists - The server key URI already exists on the server.

  • 409 ServerKeyDoesNotExists - The server key does not exist.

  • 409 UpdateSloInProgress - User tried to initiate an incompatible operation while a SLO update was in progress.

  • 409 AzureKeyVaultKeyNameNotFound - The operation could not be completed because the Azure Key Vault Key name does not exist.

  • 409 AzureKeyVaultKeyInUse - The key is currently being used by the server.

  • 409 FailoverGroupAlreadyExists - Failover group already exists on a given server. Please use different Failover Group name.

  • 409 FailoverGroupBusy - Failover Group is busy with another operation.

  • 409 DatabaseBelongsToOtherFailoverGroup - Database belongs to other Failover Group and cannot be consider a part of this one.

  • 409 DatabaseBeingAddedToFailoverGroup - The database is currently being added to Failover Group, customer needs to wait for this operation to finish to issue remove.

  • 409 DatabaseBeingRemovedFromFailoverGroup - The database is currently being removed from failover group, customer needs to wait for this operation to finish to issue add.

  • 409 FailoverGroupDnsRecordInUse - A duplicate DNS record exists for the requested endpoint.

  • 409 InvalidFailoverGroupName - Invalid Failover Group name was supplied.

  • 409 InvalidOperationForDatabaseNotInReplicationRelationship - A replication seeding operation was performed on a database that is already in a replication relationship.

  • 409 InvalidDatabaseStateForOperation - The operation is not allowed on the database in its current replication state.

  • 409 DuplicateGeoDrRelation - The databases are already in a replication relation. This is a duplicate request.

  • 409 RemoteDatabaseExists - The destination database name already exists on the destination server.

  • 409 FailoverGroupUnableToPerformGroupOperationOnDatabases - The list of databases to add/remove to/from Failover Group contains errors that are preventing operation to complete.

  • 429 SubscriptionTooManyCreateUpdateRequests - Requests beyond max requests that can be processed by available resources.

  • 429 SubscriptionTooManyRequests - Requests beyond max requests that can be processed by available resources.

  • 500 OperationTimedOut - The operation timed out and automatically rolled back. Please retry the operation.

  • 503 TooManyRequests - Requests beyond max requests that can be processed by available resources.

  • 503 AzureKeyVaultConnectionFailed - The operation could not be completed on the server because attempts to connect to Azure Key Vault have failed

  • 503 AzureKeyVaultGenericConnectionError - The operation could not be completed because an error was encountered when attempting to retrieve Key Vault information .

  • 503 DatabaseUnavailable - The operation failed because the database is unavailable.

  • 504 RequestTimeout - Service request exceeded the allowed timeout.

Examples

Update failover group

Sample Request

PATCH https://management.azure.com/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/Default/providers/Microsoft.Sql/servers/failover-group-primary-server/failoverGroups/failover-group-test-1?api-version=2020-11-01-preview
{
  "properties": {
    "readWriteEndpoint": {
      "failoverPolicy": "Automatic",
      "failoverWithDataLossGracePeriodMinutes": 120
    },
    "databases": [
      "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/Default/providers/Microsoft.Sql/servers/failover-group-primary-server/databases/testdb-1"
    ]
  }
}

Sample Response

{
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/Default/providers/Microsoft.Sql/servers/failover-group-primary-server/failoverGroups/failover-group-test-3",
  "name": "failover-group-test-3",
  "type": "Microsoft.Sql/servers/failoverGroups",
  "location": "Japan East",
  "properties": {
    "readWriteEndpoint": {
      "failoverPolicy": "Automatic",
      "failoverWithDataLossGracePeriodMinutes": 120
    },
    "readOnlyEndpoint": {
      "failoverPolicy": "Disabled"
    },
    "replicationRole": "Primary",
    "replicationState": "CATCH_UP",
    "partnerServers": [
      {
        "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/Default/providers/Microsoft.Sql/servers/failover-group-secondary-server",
        "location": "Japan West",
        "replicationRole": "Secondary"
      }
    ],
    "databases": [
      "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/Default/providers/Microsoft.Sql/servers/failover-group-primary-server/databases/testdb-1"
    ]
  }
}

Definitions

FailoverGroup

A failover group.

FailoverGroupReadOnlyEndpoint

Read-only endpoint of the failover group instance.

FailoverGroupReadWriteEndpoint

Read-write endpoint of the failover group instance.

FailoverGroupReplicationRole

Local replication role of the failover group instance.

FailoverGroupUpdate

A failover group update request.

PartnerInfo

Partner server information for the failover group.

ReadOnlyEndpointFailoverPolicy

Failover policy of the read-only endpoint for the failover group.

ReadWriteEndpointFailoverPolicy

Failover policy of the read-write endpoint for the failover group. If failoverPolicy is Automatic then failoverWithDataLossGracePeriodMinutes is required.

FailoverGroup

A failover group.

Name Type Description
id
  • string

Resource ID.

location
  • string

Resource location.

name
  • string

Resource name.

properties.databases
  • string[]

List of databases in the failover group.

properties.partnerServers

List of partner server information for the failover group.

properties.readOnlyEndpoint

Read-only endpoint of the failover group instance.

properties.readWriteEndpoint

Read-write endpoint of the failover group instance.

properties.replicationRole

Local replication role of the failover group instance.

properties.replicationState
  • string

Replication state of the failover group instance.

tags
  • object

Resource tags.

type
  • string

Resource type.

FailoverGroupReadOnlyEndpoint

Read-only endpoint of the failover group instance.

Name Type Description
failoverPolicy

Failover policy of the read-only endpoint for the failover group.

FailoverGroupReadWriteEndpoint

Read-write endpoint of the failover group instance.

Name Type Description
failoverPolicy

Failover policy of the read-write endpoint for the failover group. If failoverPolicy is Automatic then failoverWithDataLossGracePeriodMinutes is required.

failoverWithDataLossGracePeriodMinutes
  • integer

Grace period before failover with data loss is attempted for the read-write endpoint. If failoverPolicy is Automatic then failoverWithDataLossGracePeriodMinutes is required.

FailoverGroupReplicationRole

Local replication role of the failover group instance.

Name Type Description
Primary
  • string
Secondary
  • string

FailoverGroupUpdate

A failover group update request.

Name Type Description
properties.databases
  • string[]

List of databases in the failover group.

properties.readOnlyEndpoint

Read-only endpoint of the failover group instance.

properties.readWriteEndpoint

Read-write endpoint of the failover group instance.

tags
  • object

Resource tags.

PartnerInfo

Partner server information for the failover group.

Name Type Description
id
  • string

Resource identifier of the partner server.

location
  • string

Geo location of the partner server.

replicationRole

Replication role of the partner server.

ReadOnlyEndpointFailoverPolicy

Failover policy of the read-only endpoint for the failover group.

Name Type Description
Disabled
  • string
Enabled
  • string

ReadWriteEndpointFailoverPolicy

Failover policy of the read-write endpoint for the failover group. If failoverPolicy is Automatic then failoverWithDataLossGracePeriodMinutes is required.

Name Type Description
Automatic
  • string
Manual
  • string