快速入门：使用适用于 Python 的 pyodbc 驱动程序进行连接

2025-06-21

在本快速入门中，将 Python 脚本连接到已创建并加载示例数据的数据库。使用适用于 Python 的 pyodbc 驱动程序连接到数据库并执行基本作，例如读取和写入数据。

pyodbc 文档 | pyodbc 源代码 | 包（PyPi）

先决条件

Python 3
- 如果还没有 Python，请根据 python.org 安装 Python 运行时和 Python Package Index (PyPI) 包管理器。
- 不想使用自己的环境？使用 GitHub Codespaces 以 devcontainer 身份打开。
来自 PyPI 的 pyodbc 包。
包含示例架构和有效连接字符串的 Fabric AdventureWorks2022 中的 SQL Server、Azure SQL 数据库或 SQL 数据库上的数据库。

设置

按照以下步骤配置开发环境，以使用 pyodbc Python 驱动程序开发应用程序。

注释

此驱动程序使用 TDS 协议，该协议默认在 SQL Server、Fabric 中的 SQL 数据库和 Azure SQL 数据库中启用。无需进行额外配置。

安装 pyodbc 包

从 PyPI 获取 pyodbc 包。

在空目录中打开命令提示符。
安装 pyodbc 包。
```
pip install pyodbc
```

检查已安装的包

可以使用 PyPI 命令行工具验证所需的包是否已安装。

使用 pip list 检查已安装的包列表。
```
pip list
```

创建 SQL 数据库

本快速入门要求在 Microsoft SQL Server、Fabric 或 Azure SQL 数据库中的 SQL 数据库上使用 AdventureWorks2022 轻型 架构。

Azure 门户只需几分钟即可创建 SQL 数据库

创建新文件

创建名为 app.py 的新文件。

添加模块 docstring。

"""
Connects to a SQL database using pyodbc
"""

导入 pyodbc 包。

from os import getenv
from dotenv import load_dotenv
from pyodbc import connect

使用 pyodbc.connect 函数连接到 SQL 数据库。

load_dotenv()
conn = connect(getenv("SQL_CONNECTION_STRING"))

在当前目录中，创建一个名为 *.env..
在文件中，为名为 *.env 的 SQL_CONNECTION_STRING连接字符串添加一个条目。将此处的示例替换为实际连接字符串值。
```
SQL_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=<server_name>;Database={<database_name>};Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"
```
小窍门

此处使用的连接字符串在很大程度上取决于要连接到的 SQL 数据库的类型。有关连接字符串及其语法的详细信息，请参阅连接字符串语法参考。

执行查询

使用 SQL 查询字符串执行查询并分析结果。

为 SQL 查询字符串创建变量。

SQL_QUERY = """
SELECT
TOP 5 c.CustomerID,
c.CompanyName,
COUNT(soh.SalesOrderID) AS OrderCount
FROM
SalesLT.Customer AS c
LEFT OUTER JOIN SalesLT.SalesOrderHeader AS soh ON c.CustomerID = soh.CustomerID
GROUP BY
c.CustomerID,
c.CompanyName
ORDER BY
OrderCount DESC;
"""

使用 cursor.execute 从数据库查询中检索结果集。
```
cursor = conn.cursor()
cursor.execute(SQL_QUERY)
```
注释

此函数实质上接受任意查询，并返回可使用 cursor.fetchone() 循环访问的结果集。

与 cursor.fetchall 循环一起使用 foreach，从数据库中获取所有记录。然后打印记录。

records = cursor.fetchall()
for r in records:
    print(f"{r.CustomerID}\t{r.OrderCount}\t{r.CompanyName}")

app.py文件。

打开终端并测试应用程序。

python app.py

下面是预期的输出。

29485   1       Professional Sales and Service
29531   1       Remarkable Bike Store
29546   1       Bulk Discount Store
29568   1       Coalition Bike Company
29584   1       Futuristic Bikes

插入一行作为事务

安全地执行 INSERT 语句并传递参数。将参数作为值传递可保护应用程序免受 SQL 注入攻击。

将库的randrange导入random添加到顶部app.py。
```
from random import randrange
```
在添加代码的 app.py 末尾生成随机的产品名称。
```
productNumber = randrange(1000)
```
小窍门

在此处生成随机的产品编号可确保可以多次运行此示例。

创建 SQL 语句字符串。

SQL_STATEMENT = """
INSERT SalesLT.Product (
Name,
ProductNumber,
StandardCost,
ListPrice,
SellStartDate
) OUTPUT INSERTED.ProductID
VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
"""

使用 cursor.execute 执行该语句。

cursor.execute(
    SQL_STATEMENT,
    (
        f'Example Product {productNumber}',
        f'EXAMPLE-{productNumber}',
        100,
        200
    )
)

使用 cursor.fetchval 提取单个结果的第一列，打印结果的唯一标识符，然后使用 connection.commit 将该操作作为事务提交。
```
resultId = cursor.fetchval()
print(f"Inserted Product ID : {resultId}")
conn.commit()
```
小窍门

也可选择使用 connection.rollback 回滚该事务。
使用 cursor.close 和 connection.close 关闭游标和连接。
```
cursor.close()
conn.close()
```
app.py文件并再次测试应用程序。
```
python app.py
```
下面是预期的输出。
```
Inserted Product ID : 1001
```

后续步骤

pyodbc有关更多示例，请访问驱动程序 GitHub 存储库，提供想法或报告问题。

GitHub 上的 pyodbc 驱动程序

通过