Context Hub 中的 Azure SQL Management SDK for Python 实战：逻辑服务器、数据库与防火墙规则的 ARM 管控指南

本篇技术指南基于 Context Hub 仓库中维护的 Azure SQL 管理 SDK（Python）文档，系统讲解如何使用azure-mgmt-sql完成 Azure Resource Manager 控制面（control-plane）操作：创建与更新逻辑服务器（logical server）、数据库、防火墙规则、故障转移组等资源。读完本篇，你将掌握该 SDK 的安装与版本固定方式、DefaultAzureCredential认证流程、SqlManagementClient的客户端构建与操作组调用模式，以及长时操作（begin_*）的等待方式，并能避开管理面与数据面混用、忘记.result()、RBAC 权限缺失等高频坑。

一、Golden Rule：控制面与数据面的边界

azure-mgmt-sql是 Azure SQL 的管理面（ARM control-plane）SDK，用于创建逻辑服务器、数据库、防火墙规则、故障转移组等 Azure SQL 资源。它的边界非常清晰：不要用它打开 SQL 连接或对数据库执行查询——那是数据面（data-plane）工作，应使用pyodbc或基于 SQL Server 驱动之上的 SQLAlchemy 完成。

标准调用模式是四步：

1. 使用azure-identity完成认证；
2. 构造SqlManagementClient；
3. 调用操作组（operation group），如servers、databases、firewall_rules；
4. 对任何begin_*长时操作调用.result()等待完成。

这套“管理面负责供给、数据面负责查询”的边界同样体现在同仓库维护的其他文档中：JavaScript 版的 arm-sql 文档 与 SQL 虚拟机管理 SDK 的 mgmt-sqlvirtualmachine 文档 均明确强调管理包不执行 SQL 语句、不建立 TDS 连接。

二、安装与版本固定

管理包应固定版本，并同时安装azure-identity以支持 Microsoft Entra ID（Azure AD）认证：

python -m pip install "azure-mgmt-sql==3.0.1" "azure-identity"

常用替代安装方式：

uv add "azure-mgmt-sql==3.0.1" azure-identity poetry add "azure-mgmt-sql==3.0.1" azure-identity

如果在 CI 中使用服务主体（service principal）认证，通常还需要设置以下环境变量：

export AZURE_SUBSCRIPTION_ID="<subscription-id>" export AZURE_TENANT_ID="<tenant-id>" export AZURE_CLIENT_ID="<client-id>" export AZURE_CLIENT_SECRET="<client-secret>"

本地开发时，Microsoft 建议先用 Azure 开发者工具登录，再由DefaultAzureCredential复用登录态：

az login

三、认证与客户端构建

SqlManagementClient是一个 Azure 管理面客户端，需要三样东西：

• 一个 Azure 凭据，通常是DefaultAzureCredential()；
• 一个订阅 ID（subscription_id）；
• 目标订阅或资源组上的 ARM 权限（RBAC）。

基础构建方式：

import os from azure.identity import DefaultAzureCredential from azure.mgmt.sql import SqlManagementClient subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"] credential = DefaultAzureCredential() client = SqlManagementClient( credential=credential, subscription_id=subscription_id, )

实用注意事项：

• 每个进程复用同一个 credential 和 client，不要为每次调用重新创建；
• DefaultAzureCredential是同时适配本地与 Azure 环境运行的最快路径；
• 本地登录成功本身不够，身份还需要具备管理目标 SQL 资源的权限。

主权云（Sovereign clouds）

如果不使用 Azure 公有云，需要同时对齐凭据 authority 与管理端点：主权云环境通常需要为凭据指定非默认的authority，并为SqlManagementClient指定非默认的base_url。

四、核心用法

4.1 列出资源组中的逻辑服务器

from azure.identity import DefaultAzureCredential from azure.mgmt.sql import SqlManagementClient credential = DefaultAzureCredential() client = SqlManagementClient(credential, subscription_id="00000000-0000-0000-0000-000000000000") for server in client.servers.list_by_resource_group("rg-app-prod"): print(server.name, server.location, server.fully_qualified_domain_name)

4.2 创建或更新逻辑服务器

服务器创建与更新属于长时操作，必须使用begin_方法并等待轮询结果：

import os from azure.identity import DefaultAzureCredential from azure.mgmt.sql import SqlManagementClient from azure.mgmt.sql.models import Server credential = DefaultAzureCredential() client = SqlManagementClient(credential, subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]) poller = client.servers.begin_create_or_update( resource_group_name="rg-app-prod", server_name="my-sql-server", parameters=Server( location="eastus", administrator_login="sqladminuser", administrator_login_password=os.environ["AZURE_SQL_ADMIN_PASSWORD"], version="12.0", minimal_tls_version="1.2", public_network_access="Enabled", ), ) server = poller.result() print(server.id) print(server.fully_qualified_domain_name)

各字段说明：

4.3 创建数据库

数据库负载通常包含location与Sku。对基础供给流程，显式构造模型类比猜测 JSON 结构更清晰：

import os from azure.identity import DefaultAzureCredential from azure.mgmt.sql import SqlManagementClient from azure.mgmt.sql.models import Database, Sku credential = DefaultAzureCredential() client = SqlManagementClient(credential, subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]) poller = client.databases.begin_create_or_update( resource_group_name="rg-app-prod", server_name="my-sql-server", database_name="appdb", parameters=Database( location="eastus", sku=Sku(name="Basic", tier="Basic"), ), ) database = poller.result() print(database.name, database.status)

Sku(name="Basic", tier="Basic")表示基础层服务层级；生产环境可按需替换为Standard、Premium等层级与对应的capacity/family组合。

4.4 列出服务器上的数据库

from azure.identity import DefaultAzureCredential from azure.mgmt.sql import SqlManagementClient credential = DefaultAzureCredential() client = SqlManagementClient(credential, subscription_id="00000000-0000-0000-0000-000000000000") for database in client.databases.list_by_server("rg-app-prod", "my-sql-server"): print(database.name, database.status)

4.5 创建或更新防火墙规则

防火墙规则通过client.firewall_rules管理。该操作不以begin_*暴露，直接返回资源：

from azure.identity import DefaultAzureCredential from azure.mgmt.sql import SqlManagementClient from azure.mgmt.sql.models import FirewallRule credential = DefaultAzureCredential() client = SqlManagementClient(credential, subscription_id="00000000-0000-0000-0000-000000000000") rule = client.firewall_rules.create_or_update( resource_group_name="rg-app-prod", server_name="my-sql-server", firewall_rule_name="office-ip", parameters=FirewallRule( start_ip_address="203.0.113.10", end_ip_address="203.0.113.10", ), ) print(rule.name, rule.start_ip_address, rule.end_ip_address)

单一 IP 时将start_ip_address与end_ip_address设为同一地址即可；203.0.113.0/24是文档示例常用的测试地址段。

4.6 删除数据库或服务器

删除操作通常同样是长时操作：

client.databases.begin_delete( resource_group_name="rg-app-prod", server_name="my-sql-server", database_name="appdb", ).result() client.servers.begin_delete( resource_group_name="rg-app-prod", server_name="my-sql-server", ).result()

五、配置要点

• subscription_id是必填项。保持显式传入，不要默认当前 Azure CLI 选中的订阅总是正确的那一个；
• SqlManagementClient面向 Azure Resource Manager，公有云的管理端点是https://management.azure.com；
• 许多创建与更新调用要求完整的资源负载，而不只是你想修改的字段，发送部分对象前请阅读对应模型页；
• 该包暴露的操作组远不止上述常见项，还包括弹性池（elastic pools）、故障转移组（failover groups）、托管实例（managed instances）、备份策略（backup policies）、同步组（sync groups）等。在假设某个资源不受支持之前，先检查客户端上的操作组。

六、常见坑

• azure-mgmt-sql仅面向管理面：它供给和配置 Azure SQL 资源，不执行 SQL 语句；
• 许多写操作使用begin_*。忘记.result()时，代码可能在 ARM 操作完成前就退出；
• 资源名是ARM 资源名，不是连接字符串或 DNS 名。请保持resource_group_name、server_name、database_name三者概念区分（JavaScript 版文档也特别提示：不要传example.database.windows.net这类 DNS 名，而应传逻辑服务器资源名）；
• Azure 认证问题往往来自RBAC 缺失而非凭据损坏。成功的az login并不能保证写权限；
• 特殊防火墙规则地址0.0.0.0是 Azure SQL 的“允许 Azure 服务”行为，不是通用公网白名单，不要随意使用；
• 跨资源保持地域假设一致。服务器与数据库的供给在负载与预期地域、SKU 组合不匹配时常常失败或行为异常；
• 该包由 Azure 管理 API 生成，仍沿用较旧的 Azure SDK 模型模式。不确定时，先核对 Microsoft Learn 上的确切模型类型，不要凭空发明字段名。

七、版本敏感注意事项

• PyPI 当前将3.0.1列为azure-mgmt-sql的最新稳定版；
• PyPI 发布页还显示预发布线4.0.0b24。除非项目明确面向该线，否则不要采用 beta 版本；
• 3.0.1是较旧的管理包发布。Microsoft Learn 参考仍然在线，但较新的 Azure SQL 平台特性可能先出现在 REST 文档或门户 UX 中，然后才进入该 Python SDK 的示例；
• PyPI 上3.0.1的元数据列出了较旧的 Python 分类器。如果项目运行在更新的 Python 版本上，请先验证安装并冒烟测试你需要的具体管理操作，不要假设该包跟随其他 Azure SDK 库的较新基线。

八、仓库内的配套参考

本文档在 Context Hub 中以content/azure/docs/mgmt-sql/python/DOC.md形式维护，前端元数据（frontmatter）声明语言为python、版本3.0.1，可被 CLI 的chub get按 ID 拉取，其内容组织规范见 Content Guide。如需横向对照，可继续阅读仓库内以下强相关文档：

• Azure SQL Management Client For JavaScript（@azure/arm-sql10.0.0）：同族管理面 SDK 的 JS/TS 版本，操作组为servers、databases、firewallRules，长时操作使用beginCreateOrUpdateAndWait；
• Azure SQL Virtual Machine Management SDK For Python：面向 SQL Server 虚拟机的管理包（azure-mgmt-sqlvirtualmachine0.5.0），同样强调“管理面不执行 SQL”；
• Azure Identity（Python）认证文档：DefaultAzureCredential与 Entra ID 认证的配套说明。

原文档列出的 Microsoft Learn 包索引、客户端参考、各操作组与模型参考、Azure 认证概览以及 PyPI 包页均为权威外部来源，读者可自行在对应平台上检索azure-mgmt-sql确认最新 API 形状；本文所有可执行示例与注意事项均以仓库内维护的3.0.1版本为准。