Skip to main content

databases

Creates, updates, deletes, gets or lists a databases resource.

Overview​

Namedatabases
TypeResource
Idazure.sql.databases

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
idstringFully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}.
namestringThe name of the resource.
autoPauseDelayintegerTime in minutes after which database is automatically paused. A value of -1 means that automatic pause is disabled.
availabilityZonestringSpecifies the availability zone the database is pinned to. Known values are: "NoPreference", "1", "2", and "3". (NoPreference, 1, 2, 3)
catalogCollationstringCollation of the metadata catalog. Known values are: "DATABASE_DEFAULT" and "SQL_Latin1_General_CP1_CI_AS". (DATABASE_DEFAULT, SQL_Latin1_General_CP1_CI_AS)
collationstringThe collation of the database.
createModestringSpecifies the mode of database creation. Default: regular database creation. Copy: creates a database as a copy of an existing database. sourceDatabaseId must be specified as the resource ID of the source database. Secondary: creates a database as a secondary replica of an existing database. sourceDatabaseId must be specified as the resource ID of the existing primary database. PointInTimeRestore: Creates a database by restoring a point in time backup of an existing database. sourceDatabaseId must be specified as the resource ID of the existing database, and restorePointInTime must be specified. Recovery: Creates a database by restoring a geo-replicated backup. sourceDatabaseId must be specified as the recoverable database resource ID to restore. Restore: Creates a database by restoring a backup of a deleted database. sourceDatabaseId must be specified. If sourceDatabaseId is the database's original resource ID, then sourceDatabaseDeletionDate must be specified. Otherwise sourceDatabaseId must be the restorable dropped database resource ID and sourceDatabaseDeletionDate is ignored. restorePointInTime may also be specified to restore from an earlier point in time. RestoreLongTermRetentionBackup: Creates a database by restoring from a long term retention vault. recoveryServicesRecoveryPointResourceId must be specified as the recovery point resource ID. Copy, Secondary, and RestoreLongTermRetentionBackup are not supported for DataWarehouse edition. Known values are: "Default", "Copy", "Secondary", "PointInTimeRestore", "Restore", "Recovery", "RestoreExternalBackup", "RestoreExternalBackupSecondary", "RestoreLongTermRetentionBackup", and "OnlineSecondary". (Default, Copy, Secondary, PointInTimeRestore, Restore, Recovery, RestoreExternalBackup, RestoreExternalBackupSecondary, RestoreLongTermRetentionBackup, OnlineSecondary)
creationDatestring (date-time)The creation date of the database (ISO8601 format).
currentBackupStorageRedundancystringThe storage account type used to store backups for this database. Known values are: "Geo", "Local", "Zone", and "GeoZone". (Geo, Local, Zone, GeoZone)
currentServiceObjectiveNamestringThe current service level objective name of the database.
currentSkuobjectThe name and tier of the SKU.
databaseIdstringThe ID of the database.
defaultSecondaryLocationstringThe default secondary region for this database.
earliestRestoreDatestring (date-time)This records the earliest start date and time that restore is available for this database (ISO8601 format).
elasticPoolIdstringThe resource identifier of the elastic pool containing this database.
encryptionProtectorstringThe azure key vault URI of the database if it's configured with per Database Customer Managed Keys.
encryptionProtectorAutoRotationbooleanThe flag to enable or disable auto rotation of database encryption protector AKV key.
failoverGroupIdstringFailover Group resource identifier that this database belongs to.
federatedClientIdstringThe Client id used for cross tenant per database CMK scenario.
freeLimitExhaustionBehaviorstringSpecifies the behavior when monthly free limits are exhausted for the free database. AutoPause: The database will be auto paused upon exhaustion of free limits for remainder of the month. BillForUsage: The database will continue to be online upon exhaustion of free limits and any overage will be billed. Known values are: "AutoPause" and "BillOverUsage". (AutoPause, BillOverUsage)
highAvailabilityReplicaCountintegerThe number of secondary replicas associated with the Business Critical, Premium, or Hyperscale edition database that are used to provide high availability. Not applicable to a Hyperscale database within an elastic pool.
identityobjectThe Azure Active Directory identity of the database.
isInfraEncryptionEnabledbooleanInfra encryption is enabled for this database.
isLedgerOnbooleanWhether or not this database is a ledger database, which means all tables in the database are ledger tables. Note: the value of this property cannot be changed after the database has been created.
keysobjectThe resource ids of the user assigned identities to use.
kindstringKind of database. This is metadata used for the Azure portal experience.
licenseTypestringThe license type to apply for this database. LicenseIncluded if you need a license, or BasePrice if you have a license and are eligible for the Azure Hybrid Benefit. Known values are: "LicenseIncluded" and "BasePrice". (LicenseIncluded, BasePrice)
locationstringThe geo-location where the resource lives. Required.
longTermRetentionBackupResourceIdstringThe resource identifier of the long term retention backup associated with create operation of this database.
maintenanceConfigurationIdstringMaintenance configuration id assigned to the database. This configuration defines the period when the maintenance updates will occur.
managedBystringResource that manages the database.
manualCutoverbooleanWhether or not customer controlled manual cutover needs to be done during Update Database operation to Hyperscale tier. This property is only applicable when scaling database from Business Critical/General Purpose/Premium/Standard tier to Hyperscale tier. When manualCutover is specified, the scaling operation will wait for user input to trigger cutover to Hyperscale database. To trigger cutover, please provide 'performCutover' parameter when the Scaling operation is in Waiting state.
maxLogSizeBytesintegerThe max log size for this database.
maxSizeBytesintegerThe max size of the database expressed in bytes.
minCapacitynumberMinimal capacity that database will always have allocated, if not paused.
pausedDatestring (date-time)The date when database was paused by user configuration or action(ISO8601 format). Null if the database is ready.
performCutoverbooleanTo trigger customer controlled manual cutover during the wait state while Scaling operation is in progress. This property parameter is only applicable for scaling operations that are initiated along with 'manualCutover' parameter. This property is only applicable when scaling database from Business Critical/General Purpose/Premium/Standard tier to Hyperscale tier is already in progress. When performCutover is specified, the scaling operation will trigger cutover and perform role-change to Hyperscale database.
preferredEnclaveTypestringType of enclave requested on the database i.e. Default or VBS enclaves. Known values are: "Default" and "VBS". (Default, VBS)
readScalestringThe state of read-only routing. If enabled, connections that have application intent set to readonly in their connection string may be routed to a readonly secondary replica in the same region. Not applicable to a Hyperscale database within an elastic pool. Known values are: "Enabled" and "Disabled". (Enabled, Disabled)
recoverableDatabaseIdstringThe resource identifier of the recoverable database associated with create operation of this database.
recoveryServicesRecoveryPointIdstringThe resource identifier of the recovery point associated with create operation of this database.
requestedBackupStorageRedundancystringThe storage account type to be used to store backups for this database. Known values are: "Geo", "Local", "Zone", and "GeoZone". (Geo, Local, Zone, GeoZone)
requestedServiceObjectiveNamestringThe requested service level objective name of the database.
restorableDroppedDatabaseIdstringThe resource identifier of the restorable dropped database associated with create operation of this database.
restorePointInTimestring (date-time)Specifies the point in time (ISO8601 format) of the source database that will be restored to create the new database.
resumedDatestring (date-time)The date when database was resumed by user action or database login (ISO8601 format). Null if the database is paused.
sampleNamestringThe name of the sample schema to apply when creating this database. Known values are: "AdventureWorksLT", "WideWorldImportersStd", and "WideWorldImportersFull". (AdventureWorksLT, WideWorldImportersStd, WideWorldImportersFull)
secondaryTypestringThe secondary type of the database if it is a secondary. Valid values are Geo, Named and Standby. Known values are: "Geo", "Named", and "Standby". (Geo, Named, Standby)
skuobjectThe database SKU. The list of SKUs may vary by region and support offer. To determine the SKUs (including the SKU name, tier/edition, family, and capacity) that are available to your subscription in an Azure region, use the Capabilities_ListByLocation REST API or one of the following commands: .. code-block:: azurecli az sql db list-editions -l -o table .. code-block:: powershell Get-AzSqlServerServiceObjective -Location
sourceDatabaseDeletionDatestring (date-time)Specifies the time that the database was deleted.
sourceDatabaseIdstringThe resource identifier of the source database associated with create operation of this database.
sourceResourceIdstringThe resource identifier of the source associated with the create operation of this database. This property is only supported for DataWarehouse edition and allows to restore across subscriptions. When sourceResourceId is specified, sourceDatabaseId, recoverableDatabaseId, restorableDroppedDatabaseId and sourceDatabaseDeletionDate must not be specified and CreateMode must be PointInTimeRestore, Restore or Recover. When createMode is PointInTimeRestore, sourceResourceId must be the resource ID of the existing database or existing sql pool, and restorePointInTime must be specified. When createMode is Restore, sourceResourceId must be the resource ID of restorable dropped database or restorable dropped sql pool. When createMode is Recover, sourceResourceId must be the resource ID of recoverable database or recoverable sql pool. When source subscription belongs to a different tenant than target subscription, “x-ms-authorization-auxiliary” header must contain authentication token for the source tenant. For more details about “x-ms-authorization-auxiliary” header see https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/authenticate-multi-tenant _.
statusstringThe status of the database. Known values are: "Online", "Restoring", "RecoveryPending", "Recovering", "Suspect", "Offline", "Standby", "Shutdown", "EmergencyMode", "AutoClosed", "Copying", "Creating", "Inaccessible", "OfflineSecondary", "Pausing", "Paused", "Resuming", "Scaling", "OfflineChangingDwPerformanceTiers", "OnlineChangingDwPerformanceTiers", "Disabled", "Stopping", "Stopped", and "Starting". (Online, Restoring, RecoveryPending, Recovering, Suspect, Offline, Standby, Shutdown, EmergencyMode, AutoClosed, Copying, Creating, Inaccessible, OfflineSecondary, Pausing, Paused, Resuming, Scaling, OfflineChangingDwPerformanceTiers, OnlineChangingDwPerformanceTiers, Disabled, Stopping, Stopped, Starting)
systemDataobjectAzure Resource Manager metadata containing createdBy and modifiedBy information.
tagsobjectResource tags.
typestringThe type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts".
useFreeLimitbooleanWhether or not the database uses free monthly limits. Allowed on one database in a subscription.
zoneRedundantbooleanWhether or not this database is zone redundant, which means the replicas of this database will be spread across multiple availability zones.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectresource_group_name, server_name, database_name, subscription_id$expand, $filterGets a database.
list_by_elastic_poolselectresource_group_name, server_name, elastic_pool_name, subscription_idGets a list of databases in an elastic pool.
list_by_serverselectresource_group_name, server_name, subscription_id$skipTokenGets a list of databases.
create_or_updateinsertresource_group_name, server_name, database_name, subscription_id, locationCreates a new database or updates an existing database.
updateupdateresource_group_name, server_name, database_name, subscription_idUpdates an existing database.
create_or_updatereplaceresource_group_name, server_name, database_name, subscription_id, locationCreates a new database or updates an existing database.
deletedeleteresource_group_name, server_name, database_name, subscription_idDeletes the database.
list_inaccessible_by_serverexecresource_group_name, server_name, subscription_idGets a list of inaccessible databases in a logical server.
exportexecresource_group_name, server_name, database_name, subscription_id, storageKeyType, storageKey, storageUri, administratorLoginExports a database.
failoverexecresource_group_name, server_name, database_name, subscription_idreplicaTypeFailovers a database.
import_methodexecresource_group_name, server_name, database_name, subscription_id, storageKeyType, storageKey, storageUri, administratorLoginImports a bacpac into a new database.
renameexecresource_group_name, server_name, database_name, subscription_id, idRenames a database.
pauseexecresource_group_name, server_name, database_name, subscription_idPauses a database.
resumeexecresource_group_name, server_name, database_name, subscription_idResumes a database.
upgrade_data_warehouseexecresource_group_name, server_name, database_name, subscription_idUpgrades a data warehouse.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
database_namestringThe name of the database. Required.
elastic_pool_namestringThe name of the elastic pool. Required.
resource_group_namestringThe name of the resource group. The name is case insensitive. Required.
server_namestringThe name of the server. Required.
subscription_idstring
$expandstringThe child resources to include in the response. Default value is None.
$filterstringAn OData filter expression that filters elements in the collection. Default value is None.
$skipTokenstringDefault value is None.
replicaTypestringThe type of replica to be failed over. Known values are: "Primary" and "ReadableSecondary". Default value is None.

SELECT examples​

Gets a database.

SELECT
id,
name,
autoPauseDelay,
availabilityZone,
catalogCollation,
collation,
createMode,
creationDate,
currentBackupStorageRedundancy,
currentServiceObjectiveName,
currentSku,
databaseId,
defaultSecondaryLocation,
earliestRestoreDate,
elasticPoolId,
encryptionProtector,
encryptionProtectorAutoRotation,
failoverGroupId,
federatedClientId,
freeLimitExhaustionBehavior,
highAvailabilityReplicaCount,
identity,
isInfraEncryptionEnabled,
isLedgerOn,
keys,
kind,
licenseType,
location,
longTermRetentionBackupResourceId,
maintenanceConfigurationId,
managedBy,
manualCutover,
maxLogSizeBytes,
maxSizeBytes,
minCapacity,
pausedDate,
performCutover,
preferredEnclaveType,
readScale,
recoverableDatabaseId,
recoveryServicesRecoveryPointId,
requestedBackupStorageRedundancy,
requestedServiceObjectiveName,
restorableDroppedDatabaseId,
restorePointInTime,
resumedDate,
sampleName,
secondaryType,
sku,
sourceDatabaseDeletionDate,
sourceDatabaseId,
sourceResourceId,
status,
systemData,
tags,
type,
useFreeLimit,
zoneRedundant
FROM azure.sql.databases
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND server_name = '{{ server_name }}' -- required
AND database_name = '{{ database_name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
AND $expand = '{{ $expand }}'
AND $filter = '{{ $filter }}'
;

INSERT examples​

Creates a new database or updates an existing database.

INSERT INTO azure.sql.databases (
tags,
location,
properties,
sku,
identity,
resource_group_name,
server_name,
database_name,
subscription_id
)
SELECT 
'{{ tags }}',
'{{ location }}' /* required */,
'{{ properties }}',
'{{ sku }}',
'{{ identity }}',
'{{ resource_group_name }}',
'{{ server_name }}',
'{{ database_name }}',
'{{ subscription_id }}'
RETURNING
id,
name,
identity,
kind,
location,
managedBy,
properties,
sku,
systemData,
tags,
type
;

UPDATE examples​

Updates an existing database.

UPDATE azure.sql.databases
SET 
sku = '{{ sku }}',
identity = '{{ identity }}',
properties = '{{ properties }}',
tags = '{{ tags }}'
WHERE 
resource_group_name = '{{ resource_group_name }}' --required
AND server_name = '{{ server_name }}' --required
AND database_name = '{{ database_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
RETURNING
id,
name,
identity,
kind,
location,
managedBy,
properties,
sku,
systemData,
tags,
type;

REPLACE examples​

Creates a new database or updates an existing database.

REPLACE azure.sql.databases
SET 
tags = '{{ tags }}',
location = '{{ location }}',
properties = '{{ properties }}',
sku = '{{ sku }}',
identity = '{{ identity }}'
WHERE 
resource_group_name = '{{ resource_group_name }}' --required
AND server_name = '{{ server_name }}' --required
AND database_name = '{{ database_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
AND location = '{{ location }}' --required
RETURNING
id,
name,
identity,
kind,
location,
managedBy,
properties,
sku,
systemData,
tags,
type;

DELETE examples​

Deletes the database.

DELETE FROM azure.sql.databases
WHERE resource_group_name = '{{ resource_group_name }}' --required
AND server_name = '{{ server_name }}' --required
AND database_name = '{{ database_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
;

Lifecycle Methods​

Gets a list of inaccessible databases in a logical server.

EXEC azure.sql.databases.list_inaccessible_by_server 
@resource_group_name='{{ resource_group_name }}' --required, 
@server_name='{{ server_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;