DNS alias for Azure SQL Database

Applies to: Azure SQL Database Azure Synapse Analytics

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

A DNS alias can be used in place of the 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.


In Azure Synapse Analytics, the Azure SQL logical server DNS alias is only supported for dedicated SQL Pool (formerly DW). For dedicated SQL pools in Azure Synapse workspaces, the DNS alias is not currently supported. What's the difference?

Common uses for a DNS alias include the following cases:

  • Create an easy to remember name for a server.
  • During initial development, your alias can refer to a test 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 server.
  • Suppose the only database in your application is moved to another server. 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 server.

Scenarios with one DNS alias

Suppose you need to switch your system to a new 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 server.

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

Cross-region support

A disaster recovery might shift your 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 server that now hosts your Azure SQL Database.

Properties of a DNS alias

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

  • Unique name: Each alias name you create is unique across all 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 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 a 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 Azure 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 uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.


The PowerShell Azure Resource Manager module is still supported, 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:


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 a server that has table auditing enabled on a database.
  • DNS alias is subject to naming restrictions.

Next steps