快速入门:使用 Python 和 Psycopg 连接到 Microsoft Fabric HorizonDB

本快速入门使用 Psycopg 3(psycopg)和 azure-identity,通过 Microsoft Entra 访问令牌连接到 Fabric HorizonDB。

Important

Fabric HorizonDB 处于公开预览阶段。 功能、限制和行为在正式发布前可能会更改。 有关详细信息,请参阅 Microsoft Fabric 预览功能。

Prerequisites

  • Python 3.10 或更高版本。
  • 一个已加载了示例架构和数据的 Fabric HorizonDB 数据库。
  • 以创建数据库的 Microsoft Entra 用户身份登录。 在当前预览版中,其他用户、服务主体和受管身份无法连接。
  • 已发布的 Fabric HorizonDB 连接体验显示的主机、端口、数据库、用户格式、令牌作用域和 TLS 模式。
  • 用于交互式 Microsoft Entra 登录的浏览器。

不要将令牌或完整 连接字符串 复制到源代码中。

创建项目

mkdir horizondb-python
cd horizondb-python
python -m venv .venv

为您的 shell 激活虚拟环境,然后安装依赖项:

python -m pip install "psycopg[binary]" azure-identity

对于已部署的应用程序,请评估 psycopg 安装选项,并固定经审查的依赖项版本。

配置连接

在 Fabric HorizonDB 连接界面中设置这些环境变量:

HORIZONDB_HOST=<postgresql-endpoint>
HORIZONDB_PORT=<port>
HORIZONDB_DATABASE=postgres
HORIZONDB_USER=<entra-identity>
HORIZONDB_TENANT_ID=<your-tenant-id>
HORIZONDB_SSLMODE=<documented-mode>
HORIZONDB_TOKEN_SCOPE=<released-token-scope>

令牌范围是针对服务的。 请针对你的预览确认它,而不是重用其他服务的范围。 数据库名称在当前预览中为postgres,即使 Fabric 项目有其他显示名称。

创建应用程序

创建 main.py:

import os
import psycopg
from azure.identity import InteractiveBrowserCredential


credential = InteractiveBrowserCredential(
    tenant_id=os.environ["HORIZONDB_TENANT_ID"]
)


def open_connection() -> psycopg.Connection:
    access_token = credential.get_token(
        os.environ["HORIZONDB_TOKEN_SCOPE"]
    ).token

    return psycopg.connect(
        host=os.environ["HORIZONDB_HOST"],
        port=int(os.environ["HORIZONDB_PORT"]),
        dbname=os.environ["HORIZONDB_DATABASE"],
        user=os.environ["HORIZONDB_USER"],
        password=access_token,
        sslmode=os.environ["HORIZONDB_SSLMODE"],
        connect_timeout=30,
        application_name="horizondb-python-quickstart",
    )


with open_connection() as connection:
    with connection.cursor() as cursor:
        cursor.execute(
            """
            SELECT
                current_database(),
                current_user,
                current_setting('server_version'),
                clock_timestamp()
            """
        )
        database_name, signed_in_user, server_version, connected_at = (
            cursor.fetchone()
        )
        print(database_name, signed_in_user, server_version, connected_at)

        cursor.execute(
            """
            SELECT
                customer.customer_name,
                count(order_row.order_id) AS order_count,
                coalesce(sum(order_row.total), 0) AS order_total
            FROM horizon_sample.customers AS customer
            LEFT JOIN horizon_sample.orders AS order_row
              ON order_row.customer_id = customer.customer_id
            WHERE customer.segment = %s
            GROUP BY customer.customer_id, customer.customer_name
            ORDER BY customer.customer_name
            """,
            ("Enterprise",),
        )

        for customer_name, order_count, order_total in cursor:
            print(customer_name, order_count, order_total)

credential.close()

使用查询参数来传递值。 不要用 f 字串或字符串串接来插值用户输入。 此示例使用交互式登录,以便您可以显式选择数据库创建者,而无需静默使用托管工作负载身份。

运行应用程序

在当前 shell 中加载所需的环境变量并运行应用程序。 在浏览器中,以数据库创建者身份登录:

python main.py

预期产出包括:

  • 数据库名称。
  • 您的 Microsoft Entra 主体的有效身份。
  • 您的预览数据库所使用的 PostgreSQL 版本。
  • 如果您完成了“加载示例数据”,会显示示例客户汇总。

示例中会显示连接错误和查询错误。 如果数据库正在恢复,请允许启动时间,并按照“连接到 Fabric HorizonDB”中描述的有限制连接重试。 在未纠正原因之前,不要重试认证或权限失败。

添加安全事务重试

只有当 PostgreSQL 报告了可重试事务中止时,才重新尝试事务,且您的应用程序可以安全重复完成整个工作单元。 对于不能重复应用的操作,请使用稳定的应用程序级幂等性密钥。

在 COMMIT 期间发生连接丢失后,千万不要盲目重试。 提交结果可能不确定。 在决定是否再次提交之前,先重新连接并核对该业务操作状态。

使用连接池

对于长期运行的应用程序:

  • 当池创建新的物理连接时获取一个新的令牌。
  • 在令牌到期前回收连接。
  • 验证暂停、扩展或维护后借入的连接。
  • 限制池大小和连接等待时间。
  • 重建已断开的连接。
  • 刷新连接时不要使用其他身份。

Troubleshoot

Error 解决方法
环境变量使用 KeyError 定义 Fabric HorizonDB 连接体验中的所有必需设置。
凭证获取失败 验证租户并以数据库创建者身份进行交互式登录。
身份验证失败 验证已发布的范围、租户、用户格式、令牌新鲜度和系统时钟。
TLS 或证书验证失败 请使用 Fabric HorizonDB TLS 指南;不要削弱验证以隐藏配置错误。
空闲时间后连接超时 允许在数据库恢复期间进行有界重试,并检查项目状态。
permission denied 确认创建者的身份、对象所有权及支持的操作。
关系不存在 运行 加载示例数据 ,或使用您自己的架构和表名称。

清理

完成后停用虚拟环境。 删除包含连接配置的本地环境文件,且不要提交它们。