本快速入门使用 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 |
确认创建者的身份、对象所有权及支持的操作。 |
| 关系不存在 | 运行 加载示例数据 ,或使用您自己的架构和表名称。 |
清理
完成后停用虚拟环境。 删除包含连接配置的本地环境文件,且不要提交它们。