Azure SQL Management Client Library

Common errors

• ModuleNotFoundError: No module named 'azure.mgmt.sql'

  cause The `azure-mgmt-sql` package or its dependencies are not installed in the Python environment, or the Python interpreter being used does not have access to the installed package.
  fix Install the library using pip: `pip install azure-mgmt-sql`

• HttpResponseError: (SubscriptionNotFound) The requested subscription was not found.

  cause The provided Azure subscription ID is incorrect, or the authenticated identity does not have access to the specified subscription. This can also manifest as `ResourceGroupNotFound` if the resource group itself is not found or inaccessible within the subscription.
  fix Verify the subscription ID is correct and that your Azure credentials have the necessary permissions to access it. If using Azure CLI, ensure the correct subscription is set: `az account set --subscription <your_subscription_id>`.

• ClientAuthenticationError: DefaultAzureCredential failed to retrieve a token from the included credentials.

  cause The `DefaultAzureCredential` (or other credentials) could not successfully authenticate with Azure. This often happens due to misconfigured environment variables, expired tokens, or insufficient permissions for the identity attempting to authenticate.
  fix Ensure your environment variables for Azure authentication (e.g., `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`) are correctly set, or use `az login` to authenticate via Azure CLI if running locally. If using managed identities, ensure the identity has been assigned to the resource and has appropriate roles.

• HttpResponseError: (InvalidApiVersionParameter) The api-version 'YYYY-MM-DD-preview' is invalid.

  cause The API version specified for a particular Azure SQL management operation is either incorrect, outdated, or not supported for the requested resource type or region. Azure SDKs often ship with specific API versions tied to their release.
  fix Update the `azure-mgmt-sql` library to the latest version (`pip install --upgrade azure-mgmt-sql`) to use a supported API version, or consult the Azure REST API documentation for the specific operation to find the correct `api-version` to pass as a keyword argument if overriding is necessary.

Warnings

• breaking Migration from older Azure SDK (Track 1) clients to current (Track 2) clients involves significant breaking changes in client construction, authentication, and method signatures.
  Fix: Adopt `azure-identity` for authentication (e.g., `DefaultAzureCredential`). Client constructors now typically require a credential object and `subscription_id`. Method parameters and return types have been updated to be more consistent with the Azure REST API and Pythonic conventions. Consult the official Azure SDK documentation for the specific version.
• gotcha Many Azure SQL management operations are resource group-scoped. Operations like creating a server or database, or getting specific properties, require the resource group name in addition to the resource name.
  Fix: Always be mindful of the required scope for an operation. If an operation fails with a 'resource not found' or 'bad request' error, double-check if the resource group name is correctly provided and if the resource actually exists within that resource group.
• gotcha Azure SDK for Python offers both synchronous and asynchronous clients (e.g., `SqlManagementClient` vs `AsyncSqlManagementClient`). Mixing these can lead to runtime errors.
  Fix: Decide whether you need synchronous or asynchronous operations for your application. If using `asyncio`, import and instantiate the `AsyncSqlManagementClient` and `await` its methods. For synchronous operations, use `SqlManagementClient` and do not use `await`.
• gotcha List operations (e.g., `servers.list()`, `databases.list_by_server()`) return an iterable object (a 'pager') which needs to be iterated over to fetch all results, rather than a simple Python list.
  Fix: Always iterate over the result of a list operation. For example, `for server in sql_client.servers.list():` or convert to a list explicitly if all results are needed upfront: `all_servers = list(sql_client.servers.list())`.
• gotcha The `azure-mgmt-sql` library has a dependency on `six`. If `six` is not installed in the environment, a `ModuleNotFoundError` will occur when importing the library.
  Fix: Ensure that the `six` package is installed in your Python environment. You can install it using `pip install six`. Typically, `pip install azure-mgmt-sql` should handle this dependency, but in some minimal environments or specific `pip` versions, it might require explicit installation.
• breaking `azure-mgmt-sql` or its dependencies require the `six` package, which was not found during import. This prevents the library from being used.
  Fix: Install the `six` package explicitly using `pip install six` or ensure that `azure-mgmt-sql` is installed in an environment where all its transitive dependencies are correctly resolved (e.g., `pip install azure-mgmt-sql` should typically pull `six`).

Install

• pip install azure-mgmt-sql azure-identity Install core and authentication

Imports

• SqlManagementClient
  wrong:

  from azure.mgmt.sql.sql_management_client import SqlManagementClient

  correct:

  from azure.mgmt.sql import SqlManagementClient

  The client class is directly available under the top-level package.
• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

  Standard authentication credential for Azure SDK (Track 2).

Quickstart

This quickstart demonstrates how to authenticate with Azure using `DefaultAzureCredential`, instantiate the `SqlManagementClient`, and then list all Azure SQL Servers within a specified subscription. Ensure `AZURE_SUBSCRIPTION_ID` is set in your environment variables for authentication.

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.sql import SqlManagementClient

# Set your Azure Subscription ID in environment variables or replace directly
# e.g., AZURE_SUBSCRIPTION_ID = 'your-subscription-id'
subscription_id = os.environ.get('AZURE_SUBSCRIPTION_ID', 'YOUR_SUBSCRIPTION_ID')

if subscription_id == 'YOUR_SUBSCRIPTION_ID':
    raise ValueError("Please set the AZURE_SUBSCRIPTION_ID environment variable or replace 'YOUR_SUBSCRIPTION_ID'")

# Authenticate using DefaultAzureCredential
# This tries a series of authentication methods (environment variables, managed identity, VS Code, Azure CLI, etc.)
credential = DefaultAzureCredential()

# Create a SQL Management Client
sql_client = SqlManagementClient(credential, subscription_id)

print(f"Listing SQL Servers in subscription '{subscription_id}':")
# List all SQL Servers in the subscription
try:
    sql_servers = sql_client.servers.list()
    for server in sql_servers:
        print(f"  - Server Name: {server.name}, Location: {server.location}")
except Exception as e:
    print(f"An error occurred: {e}")