快速入门：从 Jupyter Notebook 连接到 SQL 数据库

在本快速入门中，使用Visual Studio Code中的Jupyter Notebook快速获取业务洞察。 使用mssql-pythonPython驱动连接SQL数据库，读取数据，然后格式化以便用于邮件、报告和演示文稿。

驱动程序 mssql-python 不需要 Windows 计算机上的任何外部依赖项。 驱动程序通过单个 pip 安装来安装它所需的一切，使你能够将最新版本的驱动程序用于新脚本，同时不会影响那些没有时间升级和测试的其他脚本。

mssql-python 文档 | mssql-python 源代码 | 包 （PyPI） | Visual Studio Code

先决条件

• Python 3.10 或更高版本

• 如果还没有 Python，请从 python.org 安装 Python 运行时和 pip 包管理器。

• 不想使用自己的环境？ 遵循容器和本地开发，创建一个可复现的开发容器或 GitHub Codespaces 环境。

• 具有以下扩展的 Visual Studio Code：

  • 适用于 Visual Studio Code 的 Python 扩展

  • Visual Studio Code 的 Jupyter 扩展

• Azure Command-Line 接口（CLI） 用于在 macOS 和 Linux 上进行无密码身份验证。

• 如果尚未安装 uv，请按照 安装说明操作。

• 在 SQL Server、Azure SQL 数据库或 Fabric 中的 SQL 数据库上使用 AdventureWorks2025 示例架构和有效连接字符串的数据库。

• 安装一次性操作系统特定的先决条件。

  • 高山
  • Debian/Ubuntu
  • RHEL
  • SUSE
  • openSUSE
  • macOS

  apk add libtool krb5-libs krb5-dev
  

创建 SQL 数据库

在以下平台之一创建或连接SQL数据库：

创建项目并运行代码

• 创建新项目
• 添加依赖项
• 启动 Visual Studio Code
• 更新 pyproject.toml
• 保存连接字符串
• 创建 Jupyter Notebook
• 在表中显示结果
• 在图表中显示结果

创建新项目

1. 在开发目录中打开命令提示符。 如果没有，可以创建一个新的目录，比如 python 或 scripts。 避免在OneDrive上放置文件夹，因为同步会影响管理虚拟环境。

2. 使用 . 创建一个新uv。

   uv init jupyter-notebook-qs
   cd jupyter-notebook-qs
   

添加依赖项

在同一目录中，安装 mssql-python、python-dotenvrich、、pandas和matplotlib包。 然后添加 ipykernel 并 uv 作为开发依赖项。 VS Code 需要使用 ipykernel 来运行笔记本单元格，并使用 uv 在笔记本单元中管理包。

uv add mssql-python python-dotenv rich pandas matplotlib
uv add --dev ipykernel
uv add --dev uv

启动 Visual Studio Code

在同一目录中运行以下命令。

code .

更新 pyproject.toml

1. pyproject.toml 包含项目的元数据。

2. 更新说明以更具描述性。

   description = "A quick example using the mssql-python driver and Jupyter Notebooks."
   

3. 保存并关闭该文件。

保存连接字符串

1. 打开.gitignore文件，并为.env文件添加一个排除项。 文件应类似于此示例。 完成后，请务必保存并关闭它。

   # Python-generated files
   __pycache__/
   *.py[oc]
   build/
   dist/
   wheels/
   *.egg-info
   
   # Virtual environments
   .venv
   
   # Connection strings and secrets
   .env
   

2. 在当前目录中，创建一个名为 .env 的新文件。

3. 在 .env 文件中，为连接字符串 SQL_CONNECTION_STRING 添加一个条目。 将此处的示例替换为实际连接字符串值。

   SQL_CONNECTION_STRING="Server=<server_name>;Database=<database_name>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"
   

   小窍门

   此处使用的连接字符串在很大程度上取决于要连接到的 SQL 数据库的类型。 如果要连接到 Fabric 中的 Azure SQL 数据库 或 SQL 数据库，请使用连接字符串选项卡中的 ODBC 连接字符串。可能需要根据方案调整身份验证类型。 有关连接字符串及其语法的详细信息，请参阅 连接字符串语法参考。

创建 Jupyter Notebook

1. 选择 “文件”，然后从列表中选择 “新建文件和Jupyter Notebook ”。 此时会打开一个新笔记本。

2. 选择 “文件”，然后选择 “另存为...” ，并为新笔记本命名。

3. 在第一个单元格中添加以下导入。

   from os import getenv
   from mssql_python import connect
   from dotenv import load_dotenv
   from rich.console import Console
   from rich.table import Table
   import pandas as pd
   import matplotlib.pyplot as plt
   

4. 使用笔记本顶部的 “+ Markdown ”按钮添加新的 Markdown 单元格。

5. 将以下文本添加到新的 markdown 单元格。

   ## Define queries for use later
   

6. 选择单元格工具栏中的 复选标记 或使用键盘快捷方式 Ctrl+Enter 或 Shift+Enter 呈现 markdown 单元格。

7. 使用笔记本顶部的“ + 代码 ”按钮添加新的代码单元格。

8. 将以下代码添加到新代码单元。

   SQL_QUERY_ORDERS_BY_CUSTOMER = """
   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;
   """
   
   SQL_QUERY_SPEND_BY_CATEGORY = """
   select top 10
   pc.Name as ProductCategory,
   SUM(sod.OrderQty * sod.UnitPrice) as Spend
   from SalesLT.SalesOrderDetail sod
   inner join SalesLT.SalesOrderHeader soh on sod.salesorderid = soh.salesorderid
   inner join SalesLT.Product p on sod.productid = p.productid
   inner join SalesLT.ProductCategory pc on p.ProductCategoryID = pc.ProductCategoryID
   GROUP BY pc.Name
   ORDER BY Spend;
   """
   

在表中显示结果

1. 使用笔记本顶部的 “+ Markdown ”按钮添加新的 Markdown 单元格。

2. 将以下文本添加到新的 markdown 单元格。

   ## Print orders by customer and display in a table
   

3. 选择单元格工具栏中的 复选标记 或使用键盘快捷方式 Ctrl+Enter 或 Shift+Enter 呈现 markdown 单元格。

4. 使用笔记本顶部的“ + 代码 ”按钮添加新的代码单元格。

5. 将以下代码添加到新代码单元。

   load_dotenv()
   with connect(getenv("SQL_CONNECTION_STRING")) as conn: # type: ignore
       with conn.cursor() as cursor:
           cursor.execute(SQL_QUERY_ORDERS_BY_CUSTOMER)
           if cursor:
               table = Table(title="Orders by Customer")
               # https://rich.readthedocs.io/en/stable/appendix/colors.html
               table.add_column("Customer ID", style="bright_blue", justify="center")
               table.add_column("Company Name", style="bright_white", justify="left")
               table.add_column("Order Count", style="bold green", justify="right")
   
               records = cursor.fetchall()
   
               for r in records:
                   table.add_row(f"{r.CustomerID}",
                                   f"{r.CompanyName}", f"{r.OrderCount}")
   
               Console().print(table)
   

   小窍门

   在 macOS 上, ActiveDirectoryInteractive 和 ActiveDirectoryDefault 都可用于 Microsoft Entra 身份验证。 ActiveDirectoryInteractive 每次运行脚本时都会提示你登录。 为避免重复登录提示，请通过Azure CLI运行 az login，然后使用ActiveDirectoryDefault，该登录可重复使用缓存的凭证。

6. 使用笔记本顶部的“ 全部运行 ”按钮运行笔记本。

7. 出现提示时，选择 jupyter-notebook-qs 内核。

在图表中显示结果

1. 查看最后一个单元格的输出。 您应该会看到一个包含三列和五行的表格。

2. 使用笔记本顶部的 “+ Markdown ”按钮添加新的 Markdown 单元格。

3. 将以下文本添加到新的 markdown 单元格。

   ## Display spend by category in a horizontal bar chart
   

4. 选择单元格工具栏中的 复选标记 或使用键盘快捷方式 Ctrl+Enter 或 Shift+Enter 呈现 markdown 单元格。

5. 使用笔记本顶部的“ + 代码 ”按钮添加新的代码单元格。

6. 将以下代码添加到新代码单元。

   with connect(getenv("SQL_CONNECTION_STRING")) as conn: # type: ignore
       data = pd.read_sql_query(SQL_QUERY_SPEND_BY_CATEGORY, conn)
       # Set the style - use print(plt.style.available) to see all options
       plt.style.use('seaborn-v0_8-notebook')
       plt.barh(data['ProductCategory'], data['Spend'])
   

7. 使用 “执行单元格 ”按钮或 Ctrl+Alt+Enter 运行单元格。

8. 查看结果。 将此笔记本设为个人专属。

后续步骤

通过这些文章继续深入学习：

• 构建连接字符串 ，配置不同SQL数据库类型和认证方法的连接。
• pandas 集成，可将查询结果直接加载到 DataFrame 中，以便在笔记本中进行分析。
• Apache Arrow 集成，支持使用 Apache Arrow 处理列式数据，以实现高性能分析。