DNS alias for Azure SQL Database

Azure SQL Database has a Domain Name System (DNS) server. PowerShell and REST APIs accept calls to create and manage DNS aliases for your SQL Database server name.

A DNS alias can be used in place of the Azure SQL Database server name. Client programs can use the alias in their connection strings. The DNS alias provides a translation layer that can redirect your client programs to different servers. This layer spares you the difficulties of having to find and edit all the clients and their connection strings.

Common uses for a DNS alias include the following cases:

  • Create an easy to remember name for an Azure SQL Server.
  • During initial development, your alias can refer to a test SQL Database server. When the application goes live, you can modify the alias to refer to the production server. The transition from test to production does not require any modification to the configurations several clients that connect to the database server.
  • Suppose the only database in your application is moved to another SQL Database server. Here you can modify the alias without having to modify the configurations of several clients.
  • During a regional outage you use geo-restore to recover your database in a different server and region. You can modify your existing alias to point to the new server so that the existing client application could re-connect to it.

Domain Name System (DNS) of the Internet

The Internet relies on the DNS. The DNS translates your friendly names into the name of your Azure SQL Database server.

Scenarios with one DNS alias

Suppose you need to switch your system to a new Azure SQL Database server. In the past you needed to find and update every connection string in every client program. But now, if the connection strings use a DNS alias, only an alias property must be updated.

The DNS alias feature of Azure SQL Database can help in the following scenarios:

Test to production

When you start developing the client programs, have them use a DNS alias in their connection strings. You make the properties of the alias point to a test version of your Azure SQL Database server.

Later when the new system goes live in production, you can update the properties of the alias to point to the production SQL Database server. No change to the client programs is necessary.

Cross-region support

A disaster recovery might shift your SQL Database server to a different geographic region. For a system that was using a DNS alias, the need to find and update all the connection strings for all clients can be avoided. Instead, you can update an alias to refer to the new SQL Database server that now hosts your database.

Properties of a DNS alias

The following properties apply to each DNS alias for your SQL Database server:

  • Unique name: Each alias name you create is unique across all Azure SQL Database servers, just as server names are.
  • Server is required: A DNS alias cannot be created unless it references exactly one server, and the server must already exist. An updated alias must always reference exactly one existing server.
    • When you drop a SQL Database server, the Azure system also drops all DNS aliases that refer to the server.
  • Not bound to any region: DNS aliases are not bound to a region. Any DNS aliases can be updated to refer to an Azure SQL Database server that resides in any geographic region.
    • However, when updating an alias to refer to another server, both servers must exist in the same Azure subscription.
  • Permissions: To manage a DNS alias, the user must have Server Contributor permissions, or higher. For more information, see Get started with Role-Based Access Control in the Azure portal.

Manage your DNS aliases

Both REST APIs and PowerShell cmdlets are available to enable you to programmatically manage your DNS aliases.

REST APIs for managing your DNS aliases

The documentation for the REST APIs is available near the following web location:

Also, the REST APIs can be seen in GitHub at:

PowerShell for managing your DNS aliases


This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.


The PowerShell Azure Resource Manager module is still supported by Azure SQL Database, but all future development is for the Az.Sql module. For these cmdlets, see AzureRM.Sql. The arguments for the commands in the Az module and in the AzureRm modules are substantially identical.

PowerShell cmdlets are available that call the REST APIs.

A code example of PowerShell cmdlets being used to manage DNS aliases is documented at:

The cmdlets used in the code example are the following:

Limitations during preview

Presently, a DNS alias has the following limitations:

  • Delay of up to 2 minutes: It takes up to 2 minutes for a DNS alias to be updated or removed.
    • Regardless of any brief delay, the alias immediately stops referring client connections to the legacy server.
  • DNS lookup: For now, the only authoritative way to check what server a given DNS alias refers to is by performing a DNS lookup.
  • Table auditing is not supported: You cannot use a DNS alias on an Azure SQL Database server that has table auditing enabled on a database.
    • Table auditing is deprecated.
    • We recommend that you move to Blob Auditing.

Next steps