Quickstart: Maak verbinding met Microsoft Fabric HorizonDB met Python en psycopg

Deze quickstart gebruikt Psycopg 3 (psycopg) en azure-identity om verbinding te maken met Fabric HorizonDB met een Microsoft Entra-toegangstoken.

Important

Fabric HorizonDB is in publieke preview. Mogelijkheden, limieten en gedrag kunnen veranderen vóór algemene beschikbaarheid. Voor meer informatie, zie Microsoft Fabric-previewfuncties.

Prerequisites

  • Python 3.10 of hoger.
  • Een Fabric HorizonDB-database met het voorbeeldschema en de geladen gegevens.
  • Meld je aan als de Microsoft Entra-gebruiker die de database heeft aangemaakt. Andere gebruikers, serviceprincipals en beheerde identiteiten kunnen geen verbinding maken in de huidige preview.
  • De host, poort, database, gebruikersindeling, tokenbereik en TLS-modus die worden weergegeven door de uitgebrachte Fabric HorizonDB-verbindingsfunctie.
  • Een browser voor interactieve Microsoft Entra-aanmelding.

Kopieer geen token of complete verbindingsreeks in broncode.

Het project maken

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

Activeer de virtuele omgeving voor uw shell en installeer vervolgens de afhankelijkheden:

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

Evalueer voor uitgerolde applicaties je psycopg installatieopties en zet beoordeelde afhankelijkheidsversies vast.

Configureer de verbinding

Stel deze omgevingsvariabelen in vanuit de Fabric HorizonDB-verbindingservaring:

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>

De tokenscope is servicespecifiek. Bevestig dit voor je preview in plaats van een scope van een andere service te hergebruiken. De databasenaam staat postgres in de huidige voorbeeldweergave, zelfs wanneer het Fabric-item een andere weergavenaam heeft.

De toepassing maken

Maak 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()

Gebruik queryparameters voor waarden. Interpoleer gebruikersinput niet met f-strings of string-concatenatie. Dit voorbeeld gebruikt interactieve aanmelding zodat u expliciet de maker van de database kunt selecteren in plaats van stilzwijgend een gehoste workload-identiteit te gebruiken.

De toepassing uitvoeren

Laad de benodigde omgevingsvariabelen in uw huidige shell en start de applicatie. Log in in de browser als databasemaker:

python main.py

De verwachte output omvat:

  • De naam van de database.
  • De effectieve identiteit voor uw Microsoft Entra-principal.
  • De PostgreSQL-versie die door uw preview-database wordt gebruikt.
  • De voorbeeldklanten worden geaggregeerd als u Samplegegevens laden hebt voltooid.

Het voorbeeld toont verbindings- en queryfouten. Als de database wordt hervat, sta dan opstarttijd toe en gebruik begrensde verbindingsproberingen zoals beschreven in Connect to Fabric HorizonDB. Probeer geen verificatie- of machtigingsfouten opnieuw zonder de oorzaak te corrigeren.

Veilige transactieherpoging toevoegen

Probeer een transactie alleen opnieuw wanneer PostgreSQL een herhaalbare transactieafbreking meldt en uw applicatie veilig de volledige werkeenheid kan herhalen. Gebruik een stabiele idempotentiesleutel op applicatieniveau voor bewerkingen die niet twee keer mogen worden toegepast.

Probeer het nooit blindelings opnieuw na een verbindingsverlies tijdens COMMIT. Het commitresultaat kan onbepaald zijn. Maak opnieuw verbinding en stem de bedrijfsbewerking af voordat je beslist of je deze opnieuw indient.

Gebruik verbindingspools

Voor een langdurige applicatie:

  • Een nieuw token verkrijgen wanneer de pool een nieuwe fysieke verbinding aanmaakt.
  • Vernieuw verbindingen voordat het token verloopt.
  • Valideer verbindingen die zijn geleend na pauze, opschalen of onderhoud.
  • Beperk de poolgrootte en de wachttijd van de verbinding.
  • Maak verbroken verbindingen opnieuw aan.
  • Gebruik geen andere identiteit bij het verversen van een verbinding.

Troubleshoot

Fout Oplossing
KeyError voor een omgevingsvariabele Definieer elke vereiste instelling uit de Fabric HorizonDB-verbindingservaring.
Credential-verwerving mislukt Controleer de tenant en log interactief in als de maker van de database.
Verificatie mislukt Controleer de toegekende scope, tenant, gebruikersformaat, tokenversheid en systeemklok.
TLS- of certificaatvalidatie mislukt Gebruik de TLS-richtlijnen van Fabric HorizonDB; verzwak de verificatie niet om een configuratiefout te verbergen.
Verbinding verloopt na inactiviteit Sta beperkte herhalingen toe terwijl de database wordt hervat en controleer de status van het item.
permission denied Bevestig de identiteit van de maker, eigendom van het object en de ondersteunde bewerking.
Tabel bestaat niet Voer Load sample data uit of gebruik uw eigen schema- en tabelnamen.

Schoonmaken

Schakel de virtuele omgeving uit als je klaar bent. Verwijder lokale omgevingsbestanden die verbindingsconfiguratie bevatten en commit deze niet.