此快速入門使用 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 登入的瀏覽器。
不要把 token 或完整的 連接字串 複製到原始碼裡。
建立專案
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 版本。
- 如果您已完成 載入範例資料,就會顯示範例客戶彙總資料。
範例會顯示連線與查詢錯誤。 如果資料庫正在恢復,請允許啟動時間,並依照 Connect to Fabric HorizonDB 中所述的限制連線重試。 在未解決原因之前,不要重試因驗證失敗或權限不足而失敗的作業。
新增安全的事務重試
只有當 PostgreSQL 回報可重試的交易中止,且您的應用程式能安全重複整個工作單元時,才可重試交易。 對於不能重複套用的操作,請使用穩定的應用程式層級冪等性金鑰。
在 COMMIT 期間發生連線中斷後,千萬不要盲目重試。 提交結果可能不確定。 在決定是否再次提交之前,先重新連線並確認業務作業狀態。
使用連線池
對於長期執行的應用程式:
- 當池建立新的實體連線時,取得新的令牌。
- 在令牌到期前回收連線。
- 驗證暫停、擴展或維護後借入的連線。
- 限制集區大小與連線等待時間。
- 重建中斷的連線。
- 重新整理連線時不要替換其他身分識別。
故障排除
| 錯誤 | Resolution |
|---|---|
KeyError 用於環境變數 |
定義 Fabric HorizonDB 連線體驗中所有必要的設定。 |
| 憑證取得失敗 | 驗證租戶並以資料庫建立者身分互動登入。 |
| 認證失敗 | 驗證已釋出的範圍、租戶、使用者格式、權杖新鮮度及系統時鐘。 |
| TLS 或憑證驗證失敗 | 請遵循 Fabric HorizonDB TLS 指引;不要為了掩蓋設定錯誤而弱化驗證。 |
| 連線在閒置時間後逾時 | 允許在資料庫恢復期間進行有界重試,並檢查項目狀態。 |
permission denied |
確認建立者的身份、物件所有權及支援的操作方式。 |
| relation 不存在 | 執行 載入範例資料 ,或使用您自己的結構與資料表名稱。 |
清理
完成後停用虛擬環境。 移除包含連線設定的本機環境檔案,且不要提交它們。