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

在本快速入门中，你将使用 Visual Studio Code 中的 Jupyter Notebook 快速获取业务见解。 使用适用于 Python 的 mssql-python 驱动程序连接到 SQL 数据库 并读取格式的数据，以便在电子邮件、报表演示文稿等中使用。

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

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

先决条件

• Python 3

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

  • 更倾向于不使用自己的环境吗？ 使用 GitHub Codespaces 以 devcontainer 身份打开。

    

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

  • 适用于 Visual Studio Code 的 Python 扩展

  • Visual Studio Code 的 Jupyter 扩展

• 如果尚未安装uv，请按照uv中的说明安装https://docs.astral.sh/uv/getting-started/installation/。

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

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

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

  apk add libtool krb5-libs krb5-dev
  

创建 SQL 数据库

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

创建项目并运行代码

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

创建新项目

1. 在开发目录中打开命令提示符。 如果没有目录，请创建名为“pythonscripts等”的新目录。避免 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笔记本单元格内使用诸如!uv add mssql_python之类的命令进行交互。

uv add mssql_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)
   

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. 查看结果。 将此笔记本设为个人专属。

后续步骤

访问mssql-python 驱动程序的 GitHub 存储库以获取更多示例，并贡献想法或报告问题。