Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.