Início rápido: Conectar-se ao Microsoft Fabric HorizonDB com Python e psycopg

Este quickstart usa o Psycopg 3 (psycopg) e azure-identity para se conectar ao Fabric HorizonDB com um token de acesso Microsoft Entra.

Importante

Fabric HorizonDB está em prévia pública. Capacidades, limites e comportamento podem mudar antes da disponibilidade geral. Para mais informações, consulte os recursos de pré-visualização do Microsoft Fabric.

Prerequisites

  • Python 3.10 ou posterior.
  • Um banco de dados Fabric HorizonDB com esquema de exemplo e dados carregados.
  • Faça login como o usuário do Microsoft Entra que criou o banco de dados. Outros usuários, principais de serviço e identidades gerenciadas não conseguem se conectar na pré-visualização atual.
  • O host, a porta, o banco de dados, o formato de usuário, o escopo de token e o modo TLS são mostrados pela experiência de conexão Fabric HorizonDB lançada.
  • Um navegador para login interativo do Microsoft Entra.

Não copie um token ou uma cadeia de conexão completa para o código-fonte.

Criar o projeto

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

Ative o ambiente virtual do seu shell e, em seguida, instale as dependências:

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

Para aplicações implantadas, avalie psycopg as opções de instalação e fixe as versões de dependência revisadas.

Configurar a conexão

Defina essas variáveis de ambiente a partir da experiência de conexão do 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>

O escopo do token é específico de cada serviço. Confirme isso para sua pré-visualização em vez de reutilizar um escopo de outro serviço. O nome do banco de dados está postgres na pré-visualização atual, mesmo quando o item Fabric tem outro nome de exibição.

Criar o aplicativo

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

Use parâmetros de consulta para valores. Não interpole a entrada do usuário com f-strings ou concatenação de strings. Este exemplo usa login interativo para que você possa selecionar explicitamente o criador do banco de dados em vez de usar silenciosamente uma identidade de carga de trabalho hospedada.

Executar o aplicativo

Carregue as variáveis de ambiente necessárias no seu shell atual e execute o aplicativo. No navegador, faça login como criador do banco de dados:

python main.py

A saída esperada inclui:

  • Nome do banco de dados.
  • A identidade efetiva do seu principal da Microsoft Entra.
  • A versão PostgreSQL usada pelo seu banco de dados de pré-visualização.
  • As agregações de clientes de exemplo aparecem se você concluir Carregar dados de exemplo.

O exemplo apresenta erros de conexão e consulta. Se o banco de dados estiver sendo retomado, permita tempo de inicialização e use tentativas de conexão limitadas conforme descrito em Conectar ao Fabric HorizonDB. Não repita tentativas após falhas de autenticação ou permissão sem corrigir a causa delas.

Adicionar retentativa segura de transação

Somente tente novamente uma transação quando o PostgreSQL reportar um aborto de transação retentável e seu aplicativo poderá repetir com segurança a unidade completa de trabalho. Use uma chave de idempotência estável em nível de aplicação para operações que não devem ser aplicadas duas vezes.

Nunca tente às cegas após uma perda de conexão durante COMMIT. O resultado do commit pode ser indeterminado. Reconecte e reconcilie a operação de negócios antes de decidir se deve enviá-la novamente.

Use pools de conexão

Para uma aplicação de longa duração:

  • Adquira um token novo quando o pool criar uma nova conexão física.
  • Recicle conexões antes do vencimento do token.
  • Valide as conexões emprestadas após pausa, escalamento ou manutenção.
  • Limite o tamanho do pool e o tempo de espera da conexão.
  • Recrie conexões quebradas.
  • Não substitua outra identidade ao atualizar uma conexão.

Troubleshoot

Error Resolução
KeyError para uma variável de ambiente Defina todas as configurações necessárias da experiência de conexão do Fabric HorizonDB.
Falha na obtenção de credenciais Verifique o tenant e entre interativamente como o criador do banco de dados.
Falha na autenticação Verifique o escopo liberado, o locatário, o formato do usuário, a atualização do token e o relógio do sistema.
TLS ou validação de certificado falha Use as orientações TLS do Fabric HorizonDB; não enfraqueça a verificação para ocultar um erro de configuração.
Expira o tempo de conexão após o tempo ocioso Permita tentativas limitadas enquanto o banco de dados volta a funcionar e inspecione o estado do item.
permission denied Confirme a identidade do criador, a propriedade do objeto e a operação suportada.
Relação não existe Execute Carregar dados de exemplo ou use seus próprios nomes de esquema e tabela.

Limpeza

Desative o ambiente virtual quando terminar. Remova arquivos de ambiente local que contenham configuração de conexão e não os confirme.