Share via

Servers - Create Or Update

Service:
SQL Database
API Version:
2025-01-01

Creates or updates a server.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}?api-version=2025-01-01

URI Parameters

Name In Required Type Description
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.
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 Required Type Description
location True

string

Resource location.
identity

ResourceIdentity

The Azure Active Directory identity of the server.
properties.administratorLogin

string

Administrator username for the server. Once created it cannot be changed.
properties.administratorLoginPassword

string

The administrator login password (required for server creation).
properties.administrators

ServerExternalAdministrator

The Azure Active Directory administrator can be utilized during server creation and for server updates, except for the azureADOnlyAuthentication property. To update the azureADOnlyAuthentication property, individual API must be used.
properties.createMode

ServerCreateMode

Create mode for server, only valid values for this are Normal and Restore.
properties.federatedClientId

string (uuid)

The Client id used for cross tenant CMK scenario
properties.isIPv6Enabled

ServerNetworkAccessFlag

Whether or not to enable IPv6 support for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled'
properties.keyId

string

A CMK URI of the key to use for encryption.
properties.minimalTlsVersion

MinimalTlsVersion

Minimal TLS version. Allowed values: 'None', 1.0', '1.1', '1.2', '1.3'
properties.primaryUserAssignedIdentityId

string

The resource id of a user assigned identity to be used by default.
properties.publicNetworkAccess

ServerPublicNetworkAccessFlag

Whether or not public endpoint access is allowed for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled' or 'SecuredByPerimeter'
properties.restrictOutboundNetworkAccess

ServerNetworkAccessFlag

Whether or not to restrict outbound network access for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled'
properties.retentionDays

integer (int32)

Number of days this server will stay soft-deleted.
properties.version

string

The version of the server.
tags

object

Resource tags.

Responses

Name Type Description
200 OK

Server

Successfully updated the server.
201 Created

Server

Successfully created the server.
202 Accepted

Accepted

Headers

Location: string
Other Status Codes

ErrorResponse

*** Error Responses: ***

  • 400 ManagedInstanceStoppingOrStopped - Conflicting operation submitted while instance is in stopping/stopped state

  • 400 ManagedInstanceStarting - Conflicting operation submitted while instance is in starting state

  • 400 NameAlreadyExistsSoftDeleted - The server name requested is taken by a server in soft deleted state. Purge or recover the server to unblock.

  • 400 MissingIdentityId - No user assigned identity is provided when the identity type is set to UserAssigned

  • 400 InvalidPrimaryIdentityId - User provides a value for PrimaryUserIdentityId but the same is not listed in the IdentityId parameter

  • 400 PECsNotExistingToDenyPublicNetworkAccess - Unable to set Deny Public Network Access to Yes since there is no private endpoint enabled to access the server. Please set up private endpoints and retry the operation (https://docs.microsoft.com/azure/sql-database/sql-database-private-endpoint-overview#how-to-set-up-private-link-for-azure-sql-database).

  • 400 NameAlreadyExists - The provided name already exists.

  • 400 UmiMissingAkvPermissions - PrimaryUserAssignedIdentityId provided by user does not have access to KeyId provided

  • 400 MissingPrimaryIdentity - PrimaryUserAssignedIdentityId provided by user does not have access to KeyId provided

  • 400 ProvisioningDisabled - Displays error message from resources operation authorizer as is, without changes

  • 400 PrimaryIdentityMissingPermissionForKeyId - KeyId is provided by user during create but PrimaryUserAssignedIdentityId is not provided in the API call

  • 400 InvalidIdentityTypeForKeyId - KeyId is provided by user during create but identity type is not set to 'UserAssigned'

  • 400 InvalidLoginName - The provided login name is invalid.

  • 400 InvalidUsername - Supplied user name contains invalid characters.

  • 400 Ipv6FeatureNotEnabled - User tried to turn on Ipv6 support on the server without enabling feature flag on subscription, or the feature support is currently disabled in the region.

  • 400 PasswordTooShort - The provided password is too short

  • 400 AadOnlyAuthenticationIsEnabled - Azure Active Directory Only Authentication is enabled. Please contact your system administrator.

  • 400 RegionDoesNotSupportVersion - A user attempted to create a server of a specified version in a location where that server version isn't supported.

  • 400 PasswordTooLong - The provided password is too long.

  • 400 PasswordNotComplex - The provided password is not complex enough.

  • 400 InvalidParameterValue - An invalid value was given to a parameter.

  • 400 InvalidLocation - An invalid location was specified.

  • 400 InvalidServerName - Invalid server name specified.

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

  • 400 TokenTooLong - The provided token is too long.

  • 400 CMKOperationNotAllowed - User tried to perform an operation on the server when the server did not have Azure Key Vault Access.

  • 400 RegionDoesNotAllowProvisioning - The selected location is not accepting new Windows Azure SQL Database servers. This may change at a later time.

  • 400 ServerNotFound - The requested server was not found.

  • 400 InvalidMinimalTlsVersion - Invalid minimal TLS version.

  • 400 InvalidExternalAdministratorLogin - Invalid or missing external administrator login name.

  • 400 InvalidExternalAdministratorSid - Invalid or missing external administrator object id.

  • 400 InvalidExternalAdministratorTenantId - Invalid or missing external administrator tenant id.

  • 400 ExternalAdministratorPrincipalType - Invalid or missing external administrator principal type. Please select from User, Application or Group.

  • 400 MissingExternalAdministratorWithAadOnlyAuth - In order to use Azure AD Only Authentication, please provide details of an external administrator.

  • 400 ExternalAdministratorLoginSameAsSqlAdmin - The names of the Azure Active Directory administrator and of the server admin account must be different. Please provide different values.

  • 400 ServerAdministratorNameAlreadyExists - User tried to set the external admin and the principal name already exists in the 'master' database.

  • 404 SubscriptionDoesNotHaveServer - The requested server was not found

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

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

  • 404 SubscriptionNotFound - The requested subscription was not found.

  • 409 CannotCancelOperation - The management operation is in a state that cannot be cancelled.

  • 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 UpsertLogicalServerRequestAlreadyInProgress - An ongoing logical server request is already in progress, please try your request again later.

  • 409 ServerDisabled - Server is disabled.

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

  • 409 SubscriptionDisabled - Subscription is disabled.

  • 409 ServerQuotaExceeded - Server cannot be added to a subscription because it will exceed quota.

  • 409 ServerAlreadyExists - Duplicate server name.

  • 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.

  • 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.

  • 429 ConflictingSubscriptionOperation - An operation is currently in progress for the subscription.

  • 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 TooManyRequests - Requests beyond max requests that can be processed by available resources.

Examples

Create server

Sample request

PUT https://management.azure.com/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/sqlcrudtest-7398/providers/Microsoft.Sql/servers/sqlcrudtest-4645?api-version=2025-01-01

{
  "properties": {
    "administratorLogin": "dummylogin",
    "administratorLoginPassword": "PLACEHOLDER",
    "administrators": {
      "principalType": "User",
      "login": "bob@contoso.com",
      "sid": "00000011-1111-2222-2222-123456789111",
      "tenantId": "00000011-1111-2222-2222-123456789111",
      "azureADOnlyAuthentication": true
    },
    "createMode": "Normal",
    "publicNetworkAccess": "Enabled",
    "restrictOutboundNetworkAccess": "Enabled",
    "isIPv6Enabled": "Enabled",
    "retentionDays": 7
  },
  "location": "Japan East"
}

Sample response

Status code:
200 
{
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/sqlcrudtest-7398/providers/Microsoft.Sql/servers/sqlcrudtest-4645",
  "name": "sqlcrudtest-4645",
  "type": "Microsoft.Sql/servers",
  "location": "japaneast",
  "kind": "v12.0",
  "properties": {
    "fullyQualifiedDomainName": "sqlcrudtest-4645.database.windows.net",
    "administratorLogin": "dummylogin",
    "version": "12.0",
    "state": "Ready",
    "publicNetworkAccess": "Enabled",
    "restrictOutboundNetworkAccess": "Enabled",
    "isIPv6Enabled": "Enabled",
    "retentionDays": 7,
    "administrators": {
      "principalType": "User",
      "login": "bob@contoso.com",
      "sid": "00000011-1111-2222-2222-123456789111",
      "tenantId": "00000011-1111-2222-2222-123456789111",
      "azureADOnlyAuthentication": true
    },
    "privateEndpointConnections": [
      {
        "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/sqlcrudtest-7398/providers/Microsoft.Sql/servers/sqlcrudtest-4645/privateEndpointConnections/private-endpoint-name-00000000-1111-2222-3333-444444444444",
        "properties": {
          "provisioningState": "Ready",
          "privateEndpoint": {
            "id": "/subscriptions/55555555-6666-7777-8888-999999999999/resourceGroups/Default-Network/providers/Microsoft.Network/privateEndpoints/private-endpoint-name"
          },
          "privateLinkServiceConnectionState": {
            "status": "Approved",
            "description": "Auto-approved",
            "actionsRequired": "None"
          }
        }
      }
    ]
  }
}
Status code:
201 
{
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/sqlcrudtest-7398/providers/Microsoft.Sql/servers/sqlcrudtest-4645",
  "name": "sqlcrudtest-4645",
  "type": "Microsoft.Sql/servers",
  "location": "japaneast",
  "kind": "v12.0",
  "properties": {
    "fullyQualifiedDomainName": "sqlcrudtest-4645.database.windows.net",
    "administratorLogin": "dummylogin",
    "publicNetworkAccess": "Enabled",
    "restrictOutboundNetworkAccess": "Enabled",
    "isIPv6Enabled": "Enabled",
    "retentionDays": 7,
    "version": "12.0",
    "state": "Ready",
    "administrators": {
      "principalType": "User",
      "login": "bob@contoso.com",
      "sid": "00000011-1111-2222-2222-123456789111",
      "tenantId": "00000011-1111-2222-2222-123456789111",
      "azureADOnlyAuthentication": true
    },
    "privateEndpointConnections": [
      {
        "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/sqlcrudtest-7398/providers/Microsoft.Sql/servers/sqlcrudtest-4645/privateEndpointConnections/private-endpoint-name-00000000-1111-2222-3333-444444444444",
        "properties": {
          "provisioningState": "Ready",
          "privateEndpoint": {
            "id": "/subscriptions/55555555-6666-7777-8888-999999999999/resourceGroups/Default-Network/providers/Microsoft.Network/privateEndpoints/private-endpoint-name"
          },
          "privateLinkServiceConnectionState": {
            "status": "Approved",
            "description": "Auto-approved",
            "actionsRequired": "None"
          }
        }
      }
    ]
  }
}
Status code:
202

Definitions

Name Description
AdministratorType

Type of the sever administrator.
ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
ErrorResponse

Error response
ExternalGovernanceStatus

Status of external governance.
IdentityType

The identity type. Set this to 'SystemAssigned' in order to automatically create and assign an Azure Active Directory principal for the resource.
MinimalTlsVersion

Minimal TLS version. Allowed values: 'None', 1.0', '1.1', '1.2', '1.3'
PrincipalType

Principal Type of the sever administrator.
PrivateEndpointConnectionProperties

Properties of a private endpoint connection.
PrivateEndpointProperty
PrivateEndpointProvisioningState

State of the private endpoint connection.
PrivateLinkServiceConnectionStateActionsRequire

The actions required for private link service connection.
PrivateLinkServiceConnectionStateProperty
PrivateLinkServiceConnectionStateStatus

The private link service connection status.
ResourceIdentity

Azure Active Directory identity configuration for a resource.
Server

An Azure SQL Database server.
ServerCreateMode

Create mode for server, only valid values for this are Normal and Restore.
ServerExternalAdministrator

Properties of a active directory administrator.
ServerNetworkAccessFlag

Whether or not to restrict outbound network access for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled'
ServerPrivateEndpointConnection

A private endpoint connection under a server
ServerPublicNetworkAccessFlag

Whether or not public endpoint access is allowed for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled' or 'SecuredByPerimeter'
ServerWorkspaceFeature

Whether or not existing server has a workspace created and if it allows connection from workspace
UserIdentity

Azure Active Directory identity configuration for a resource.

AdministratorType

Enumeration

Type of the sever administrator.

Value Description
ActiveDirectory

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.

ExternalGovernanceStatus

Enumeration

Status of external governance.

Value Description
Enabled
Disabled

IdentityType

Enumeration

The identity type. Set this to 'SystemAssigned' in order to automatically create and assign an Azure Active Directory principal for the resource.

Value Description
None
SystemAssigned
UserAssigned
SystemAssigned,UserAssigned

MinimalTlsVersion

Enumeration

Minimal TLS version. Allowed values: 'None', 1.0', '1.1', '1.2', '1.3'

Value Description
None
1.0
1.1
1.2
1.3

PrincipalType

Enumeration

Principal Type of the sever administrator.

Value Description
User
Group
Application

PrivateEndpointConnectionProperties

Object

Properties of a private endpoint connection.

Name Type Description
groupIds

string[]

Group IDs.
privateEndpoint

PrivateEndpointProperty

Private endpoint which the connection belongs to.
privateLinkServiceConnectionState

PrivateLinkServiceConnectionStateProperty

Connection state of the private endpoint connection.
provisioningState

PrivateEndpointProvisioningState

State of the private endpoint connection.

PrivateEndpointProperty

Object
Name Type Description
id

string

Resource id of the private endpoint.

PrivateEndpointProvisioningState

Enumeration

State of the private endpoint connection.

Value Description
Approving
Ready
Dropping
Failed
Rejecting

PrivateLinkServiceConnectionStateActionsRequire

Enumeration

The actions required for private link service connection.

Value Description
None

PrivateLinkServiceConnectionStateProperty

Object
Name Type Description
actionsRequired

PrivateLinkServiceConnectionStateActionsRequire

The actions required for private link service connection.
description

string

The private link service connection description.
status

PrivateLinkServiceConnectionStateStatus

The private link service connection status.

PrivateLinkServiceConnectionStateStatus

Enumeration

The private link service connection status.

Value Description
Approved
Pending
Rejected
Disconnected

ResourceIdentity

Object

Azure Active Directory identity configuration for a resource.

Name Type Description
principalId

string (uuid)

The Azure Active Directory principal id.
tenantId

string (uuid)

The Azure Active Directory tenant id.
type

IdentityType

The identity type. Set this to 'SystemAssigned' in order to automatically create and assign an Azure Active Directory principal for the resource.
userAssignedIdentities

<string,  UserIdentity>

The resource ids of the user assigned identities to use

Server

Object

An Azure SQL Database server.

Name Type Description
id

string

Resource ID.
identity

ResourceIdentity

The Azure Active Directory identity of the server.
kind

string

Kind of sql server. This is metadata used for the Azure portal experience.
location

string

Resource location.
name

string

Resource name.
properties.administratorLogin

string

Administrator username for the server. Once created it cannot be changed.
properties.administratorLoginPassword

string

The administrator login password (required for server creation).
properties.administrators

ServerExternalAdministrator

The Azure Active Directory administrator can be utilized during server creation and for server updates, except for the azureADOnlyAuthentication property. To update the azureADOnlyAuthentication property, individual API must be used.
properties.createMode

ServerCreateMode

Create mode for server, only valid values for this are Normal and Restore.
properties.externalGovernanceStatus

ExternalGovernanceStatus

Status of external governance.
properties.federatedClientId

string (uuid)

The Client id used for cross tenant CMK scenario
properties.fullyQualifiedDomainName

string

The fully qualified domain name of the server.
properties.isIPv6Enabled

ServerNetworkAccessFlag

Whether or not to enable IPv6 support for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled'
properties.keyId

string

A CMK URI of the key to use for encryption.
properties.minimalTlsVersion

MinimalTlsVersion

Minimal TLS version. Allowed values: 'None', 1.0', '1.1', '1.2', '1.3'
properties.primaryUserAssignedIdentityId

string

The resource id of a user assigned identity to be used by default.
properties.privateEndpointConnections

ServerPrivateEndpointConnection[]

List of private endpoint connections on a server
properties.publicNetworkAccess

ServerPublicNetworkAccessFlag

Whether or not public endpoint access is allowed for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled' or 'SecuredByPerimeter'
properties.restrictOutboundNetworkAccess

ServerNetworkAccessFlag

Whether or not to restrict outbound network access for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled'
properties.retentionDays

integer (int32)

Number of days this server will stay soft-deleted.
properties.state

string

The state of the server.
properties.version

string

The version of the server.
properties.workspaceFeature

ServerWorkspaceFeature

Whether or not existing server has a workspace created and if it allows connection from workspace
tags

object

Resource tags.
type

string

Resource type.

ServerCreateMode

Enumeration

Create mode for server, only valid values for this are Normal and Restore.

Value Description
Normal
Restore

ServerExternalAdministrator

Object

Properties of a active directory administrator.

Name Type Description
administratorType

AdministratorType

Type of the sever administrator.
azureADOnlyAuthentication

boolean

Azure Active Directory only Authentication enabled.
login

string

Login name of the server administrator.
principalType

PrincipalType

Principal Type of the sever administrator.
sid

string (uuid)

SID (object ID) of the server administrator.
tenantId

string (uuid)

Tenant ID of the administrator.

ServerNetworkAccessFlag

Enumeration

Whether or not to restrict outbound network access for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled'

Value Description
Enabled
Disabled

ServerPrivateEndpointConnection

Object

A private endpoint connection under a server

Name Type Description
id

string

Resource ID.
properties

PrivateEndpointConnectionProperties

Private endpoint connection properties

ServerPublicNetworkAccessFlag

Enumeration

Whether or not public endpoint access is allowed for this server. Value is optional but if passed in, must be 'Enabled' or 'Disabled' or 'SecuredByPerimeter'

Value Description
Enabled
Disabled
SecuredByPerimeter

ServerWorkspaceFeature

Enumeration

Whether or not existing server has a workspace created and if it allows connection from workspace

Value Description
Connected
Disconnected

UserIdentity

Object

Azure Active Directory identity configuration for a resource.

Name Type Description
clientId

string (uuid)

The Azure Active Directory client id.
principalId

string (uuid)

The Azure Active Directory principal id.