SQL Database API upgrade

Question

I have received a note from Microsoft to upgrade the API version used in SQL Databases. I have identified a couple of them via the templates section of these Databases.

My query is

1. What do these API versions denote in this context of the SQL Database and their functionality.
2. Second, how to update the API of these SQL Databases?

Answer 1

In ARM and Bicep templates, the apiVersion property defines which version of the Azure Resource Manager (ARM REST API schema) is used for that resource type (for example, Microsoft.Sql/servers/databases).

It tells Azure which features and properties are available when the resource is deployed or updated — not the SQL database runtime version itself.

Each resource provider (like Microsoft.Sql) releases new API versions periodically. For example:

API Version	Purpose
2014-04-01	Very old version — limited properties (deprecated)
2014-04-01	Very old version — limited properties (deprecated)
2019-06-01-preview	Introduced newer database options
2021-11-01	Supports modern features (vCore model, zone redundancy, maintenance configuration)
2023-08-01-preview	Latest public preview, includes elasticity features

When Microsoft deprecates an old API version (like 2014-04-01), your templates may still deploy successfully for now, but they will eventually fail once support is removed.

---

2. How to update the API version safely

To update, edit your ARM or Bicep templates to reference the latest supported API version.

Example

Old:

"type": "Microsoft.Sql/servers/databases/advisors",
"apiVersion": "2014-04-01",

Updated:

"type": "Microsoft.Sql/servers/databases/advisors",
"apiVersion": "2021-11-01",

https://learn.microsoft.com/en-us/rest/api/sql/

Use Azure CLI or PowerShell to list available versions:

Azure CLI

az provider show --namespace Microsoft.Sql --query "resourceTypes[].{ResourceType:resourceType,ApiVersion

1. The apiVersion in ARM templates defines which ARM schema version is used — not the SQL engine version.
2. Microsoft periodically retires old API versions.
3. Update templates to use the latest supported version for Microsoft.Sql/servers/databases.
4. Verify compatibility using the Azure CLI or REST API reference before deploying.

Answer 2

Hi @OV, Joel,

Here are the most relevant official resources:

• Azure SQL Database REST API Overview
• Databases - Update (REST API)
• API Version Retirement Notice

Hope the above steps were helpful. If you have any other questions, please feel free to contact us.

Thanks,
Vrishabh