在 Windows 上使用 Python pyodbc 连接 Azure SQL Database 与 SQL Server：官方示例实战指南-平芜编程栈

示例工程
数据库
教程
后端

【免费下载链接】sql-server-samples

Azure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge

项目地址：https://gitcode.com/gh_mirrors/sq/sql-server-samples

点击查看免费下载

本指南以 Microsoft sql-server-samples 仓库中的官方 Windows 示例（samples/tutorials/python/pyodbc/windows/README.md）为主体，讲解如何在 Windows 客户端上使用pyodbc连接器连接 Azure SQL Database 或 SQL Server 2016+，完成基础的 SELECT 与 INSERT 操作。读完本文后，你将掌握 pyodbc 连接字符串的完整写法、示例代码的执行流程，以及驱动安装、数据准备等落地环节的关键细节，可以直接把示例跑通并迁移到自己的业务代码中。

关于本示例

该示例来自仓库中的 Python 示例集，官方定位如下：

适用对象：SQL Server 2016（或更高版本）、Azure SQL Database、Azure SQL Data Warehouse（现并入 Azure Synapse）、Parallel Data Warehouse
工作负载：CRUD（增删改查）
编程语言：Python
作者：Meet Bhagdev

示例本身非常精简——只包含一个文件 sample_python_windows.py，但它完整演示了 pyodbc 连接数据库的「三板斧」：构造连接字符串、建立连接与游标、执行 SQL 并逐行读取结果。这是所有 Python + SQL Server 应用的最小可运行骨架。

开始之前：软硬件前置条件

在 Windows 客户端上运行本示例，需要依次满足以下前置条件。

软件前置条件

SQL Server 2016（或更高版本），或一个 Azure SQL Database。这是连接的目标端，示例代码中的连接信息需要指向它。
Python。原文档指向 Python 2.7.6 版本。需要特别说明的是，示例源码使用的是Python 2 语法（例如print row[0]是语句而非函数调用），如果你使用 Python 3 运行，需要将源码中的print语句改写为print(row[0])形式。实际生产中建议使用较新的 Python 3 版本，并同步调整语法。
Microsoft ODBC Driver for SQL Server（Windows 版，11 或 13）。这是 pyodbc 与 SQL Server 之间通信的底层驱动，需从微软官方渠道下载并安装。示例的连接字符串中指定的驱动名称为ODBC Driver 13 for SQL Server，安装时必须保证系统注册的驱动名与连接字符串中的名称完全一致（连接字符串中的驱动名需要去掉空格）。
pyodbc 库。在终端中执行：
```
pip install pyodbc
```
pyodbc 是 Python 生态中最常用的 ODBC 数据库连接库，它把 Python DB-API 接口映射到 ODBC 驱动之上，因此只要系统里装了对应的 ODBC 驱动，同一套代码就可以连接 SQL Server、Azure SQL Database 等多种数据源。

Azure 前置条件：准备 AdventureWorks 数据库

示例中的 SELECT 与 INSERT 语句都依赖AdventureWorks示例数据库（具体是SalesLT.Product和SalesLT.Product表所在的 SalesLT schema）。

仓库本身即为 AdventureWorks 提供了完整的安装资源：

OLTP 安装脚本与全部 CSV 数据位于 samples/databases/adventure-works/oltp-install-script/，主脚本为 instawdb.sql；

数据仓库版脚本位于>import pyodbc server = 'tcp:myserver.database.windows.net' database = 'mydb' username = 'myusername' password = 'mypassword' #Connection String cnxn = pyodbc.connect('DRIVER={ODBC Driver 13 for SQL Server};SERVER='+server+';DATABASE='+database+';UID='+username+';PWD='+ password)

各参数含义如下：

参数	示例值	说明
`server`	`tcp:myserver.database.windows.net`	目标实例地址。Azure SQL Database 的地址形如`<server>.database.windows.net`，`tcp:`前缀用于明确走 TCP 协议；连接本地 SQL Server 时则为`localhost`、`localhost\SQLEXPRESS`或主机名/实例名
`database`	`mydb`	目标数据库名，示例中为 AdventureWorks
`username`/`UID`	`myusername`	登录名；Azure SQL Database 通常使用`<user>@<server>`的格式
`password`/`PWD`	`mypassword`	登录密码
`DRIVER`	`{ODBC Driver 13 for SQL Server}`	必须与系统已安装 ODBC 驱动注册名一致，花括号用于包裹含空格的驱动名

pyodbc.connect()成功后会返回一个连接对象cnxn，再通过cnxn.cursor()取得游标cursor，后续所有 SQL 都由该游标执行。这段代码清晰地展示了 pyodbc 连接字符串的关键点：所有键值对用分号连接，键名不区分大小写，驱动名必须带花括号。

运行示例

运行步骤如下：

用文本编辑器打开 sample_python_windows.py，将server、database、username、password四个变量替换为你自己的真实值；
在终端中进入示例所在目录并执行：
```
python sample_python_windows.py
```
观察输出：程序会先打印SELECT @@version;返回的 SQL Server 版本信息，再打印 INSERT 语句返回的新插入记录的 ProductID。

示例代码逐段解析

示例共包含三个逻辑步骤，下面结合源码逐段解读。

第一步：SELECT 查询版本信息

cursor.execute("SELECT @@version;") row = cursor.fetchone() while row: print row[0] row = cursor.fetchone()

cursor.execute()执行查询但不立即获取结果；
cursor.fetchone()每次取回结果集的一行（元组）；
while row:循环遍历所有返回行，row[0]是元组的第一个字段——这里正是@@version返回的版本字符串。

这个模式（execute→fetchone→while循环）是 pyodbc 读取结果集的最基础写法，几乎所有 SELECT 场景都可以套用。

第二步：INSERT 并回读新主键

cursor.execute("INSERT SalesLT.Product (Name, ProductNumber, StandardCost, ListPrice, SellStartDate) OUTPUT INSERTED.ProductID VALUES ('SQL Server Express New 20', 'SQLEXPRESS New 20', 0, 0, CURRENT_TIMESTAMP )") row = cursor.fetchone() while row: print 'Inserted Product key is ' + str(row[0]) row = cursor.fetchone()

INSERT 语句向SalesLT.Product表插入一条新产品记录，字段覆盖Name、ProductNumber、StandardCost、ListPrice和SellStartDate（用CURRENT_TIMESTAMP取当前时间）；
关键点在于OUTPUT INSERTED.ProductID子句：它让 INSERT 语句同时把新生成的主键值作为结果集返回，从而可以直接用fetchone()取到插入行的 ProductID；
程序随后打印Inserted Product key is <id>，验证插入成功。

这种「插入后立即取回主键」的做法避免了再次查询，是写入类业务中的常用技巧。注意示例只做了 INSERT 而没有调用cnxn.commit()——如果你希望插入的数据真正落库，需要在实践中显式提交事务（或在连接字符串中配置自动提交）。

第三步：遍历结果

两段 SQL 都使用了相同的while row:读取循环。需要留意的是，示例源码运行于 Python 2 环境，print均为语句形式；若迁移到 Python 3，请改为print(row[0])、print('Inserted Product key is ' + str(row[0]))。

与 Linux 版本的对照

仓库同时提供了 Ubuntu Linux 版本（samples/tutorials/python/pyodbc/linux/README.md），其示例代码 sample_python_linux.py 与 Windows 版几乎一致，差异主要体现在：

安装方式不同：Linux 版通过apt-get安装python-dev、python-pip，ODBC 驱动通过官方安装脚本安装，pyodbc 用sudo -H pip install pyodbc；
连接代码相同：两个平台共用同一套 pyodbc API 与连接字符串结构，这正是 pyodbc 跨平台能力的最好佐证。

如果你在 macOS 或 Linux 上开发，可以参照 Python 示例集中按操作系统分目录组织的各版本；仓库还提供了使用pymssql驱动连接 SQL Server 的同类示例（如 samples/tutorials/python/pymssql/linux/README.md），可作为连接器选型时的对照参考。

注意事项与限制

Python 版本：示例源码是 Python 2 语法，运行时请按实际解释器版本调整print等语法；
ODBC 驱动版本：连接字符串中的驱动名ODBC Driver 13 for SQL Server必须与系统安装的驱动注册名一致，否则会抛出 "IM002: Driver not found" 类错误；安装新版驱动后需同步修改此名称；
SQL 版本依赖：SalesLT.Product表存在于 AdventureWorks 的 SalesLT schema，插入语句依赖该表结构与已有数据，请务必先用仓库脚本准备数据库；
事务提交：示例未显式commit()，在实际写入业务中应根据需要提交或回滚事务；
凭据安全：示例把密码硬编码在源码中，仅供学习演示；生产环境应使用环境变量、密钥管理服务或受支持的认证方式替代。