Conectar-se ao Microsoft Fabric HorizonDB

O Fabric HorizonDB expõe um endpoint PostgreSQL estável para aplicações e ferramentas PostgreSQL. Use a autenticação Microsoft Entra e as propriedades de conexão exibidas pelo banco de dados HorizonDB.

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

  • Acesso ao espaço de trabalho Fabric e ao banco de dados HorizonDB.
  • Faça login como a identidade Microsoft Entra que criou o banco de dados. Outros usuários e entidades de segurança não conseguem se conectar na pré-visualização atual.
  • O host, a porta, o nome do banco de dados, o formato do usuário, a orientação de token e as configurações de TLS vêm da experiência de conexão lançada do Fabric HorizonDB.

Poder abrir ou compartilhar o item não habilita outra identidade PostgreSQL. Não substitua o criador por um principal de serviço ou uma identidade gerenciada.

Escolha o endpoint correto

Use o endpoint PostgreSQL para:

  • O editor Fabric SQL.
  • Visual Studio Code e psql.
  • Python e drivers de aplicação.
  • DDL, DML, transações, inspeção de roles e visualizações de diagnóstico do PostgreSQL.

Não use o endpoint de análise SQL para conexões operacionais. O endpoint de análise do SQL é uma superfície analítica somente leitura sobre dados espelhados assíncronamente e pode apresentar diferentes níveis de integridade e atualidade.

Conecte-se ao editor Fabric SQL

  1. Abra o banco de dados HorizonDB no portal Fabric.

  2. Abra uma nova consulta SQL.

  3. Executar:

    SELECT
        current_database() AS database_name,
        current_user AS signed_in_user,
        pg_backend_pid() AS session_id,
        clock_timestamp() AS connected_at;
    
  4. Confirme o banco de dados esperado e a identidade efetiva.

O editor usa o contexto do Microsoft Entra com sessão iniciada. O principal chamador determina a identidade efetiva do PostgreSQL. Se o editor abrir, mas uma instrução falhar com erro de permissão, verifique se a permissão Fabric exposta pela experiência atual suporta a operação. Para o comportamento e atalhos do editor, consulte Consultar com o editor SQL.

Conectar-se ao Visual Studio Code

Instalar:

Abra a conexão a partir da barra de ferramentas Fabric:

  1. Selecione Visual Studio Code. Se necessário, abra Mais opções (...) primeiro.

    Captura de tela da ação Visual Studio Code na barra de ferramentas do banco de dados.

  2. No painel de conexão, revise os pré-requisitos de instalação e os detalhes da conexão PostgreSQL.

    Captura de tela do painel de conexão do Visual Studio Code com um host ilustrativo PostgreSQL e um nome de banco de dados postgres.

  3. Selecione Abrir no VS Code e permita o prompt de protocolo do vscode navegador.

  4. Se a caixa de diálogo de conexão não tiver sido aberta após aproximadamente 40 segundos, volte para o Fabric e selecione Retentar Abrir no Visual Studio Code.

  5. Verifique o host, a porta e o banco de dados pré-preenchidos. O nome do banco de dados é postgres na pré-visualização atual, e não o nome de exibição do item Fabric.

  6. Para Tipo de Autenticação, selecione Entra Auth.

  7. Faça login como criador do banco de dados.

  8. Digite um Nome de Conexão reconhecível e selecione Salvar e Conectar.

  9. Abra uma consulta e execute a consulta de validação na seção anterior.

No Visual Studio Code, selecione o ícone de elefante do PostgreSQL, expanda Conexões e expanda seu banco de dados e esquema. Clique com o botão direito em uma tabela e selecione Select Top 1000 para visualizar as linhas, ou clique com o botão direito no banco de dados e selecione Connect with PSQL. Atualize a árvore após as alterações de DDL.

Se a ação da barra de ferramentas não estiver disponível, confirme a habilitação da pré-visualização e que você está visualizando o item do banco de dados HorizonDB, e não seu endpoint espelhado de SQL analytics. Não copie valores de conexão de outro serviço.

Conectar-se ao psql

Instale um cliente PostgreSQL compatível com a versão reportada pelo seu banco de dados. Use as coordenadas e o modo TLS publicados para sua visualização:

psql "host=<postgresql-endpoint> port=<port> dbname=<database-name> user=<entra-identity> sslmode=<documented-mode>"

Adquira um novo token Microsoft Entra por meio do fluxo do cliente publicado. Forneça isso de forma segura quando o cliente solicitar uma credencial equivalente à senha. Não coloque o token no comando, histórico do shell, dumps de ambiente ou em um arquivo de serviço versionado.

Após conectar, execute:

SELECT
    current_database(),
    current_user,
    current_setting('server_version'),
    clock_timestamp();

Criar conexões de aplicativo

Use um driver PostgreSQL que suporte a linguagem que você usa e credenciais de token do Microsoft Entra. Novos exemplos em Python usam Psycopg 3. Para um exemplo completo, veja Conectar com Python.

Configure estes valores fora do código-fonte:

Setting Guidance
Host e porta Copie-os da experiência de conexão do Fabric HorizonDB.
Database Use postgres na visualização atual, conforme mostrado no painel de conexão do item. Não use o nome de exibição do item Fabric.
User Use o formato de identidade Microsoft Entra lançado.
Credential Adquira um token de curta duração por meio do fluxo de autenticação disponibilizado.
TLS Use as orientações exatas publicadas sslmode e sobre certificados.
Nome do aplicativo Defina um nome estável e não sensível para diagnósticos.
Timeouts Use um tempo limite de conexão finito e um tempo limite de instrução apropriado para a aplicação.

Agrupamento de conexão e atualização de tokens

Tokens de acesso têm vida curta. Um pool não deve continuar criando conexões físicas com um token expirado.

  • Adquira um token novo para cada nova conexão física ou atualização do pool.
  • Defina a vida útil do pool para que as conexões sejam substituídas antes que a credencial expire.
  • Valide uma conexão emprestada após uma pausa ou transição disruptiva.
  • Feche ou recicle conexões quebradas.
  • Mantenha o tamanho do pool dentro dos limites de conexão do Fabric HorizonDB liberados.
  • Mantenha a conexão sob a identidade do criador; uma alteração de permissão não habilita usuários adicionais do PostgreSQL.

Tentar novamente com segurança após pausa ou transição

A primeira conexão elegível a um banco de dados pausado inicia a retomada. Escalar, manter ou retomar pode interromper uma conexão.

  1. Defina um tempo limite de conexão finito.
  2. Tente novamente em caso de falhas de conexão retentáveis com backoff exponencial limitado e jitter.
  3. Abra uma nova conexão em vez de reutilizar uma que falhou.
  4. Tente novamente uma transação somente quando souber que ela não foi confirmada ou quando a operação for idempotente.
  5. Reconcilie um commit indeterminado usando uma transação de aplicativo ou chave de negócios.

Não repita tentativas após falhas de autenticação, configuração inválida, operações não suportadas ou erros de permissão em um loop fechado. O Fabric HorizonDB não reexecuta SQL ou transações automaticamente.

Solucionar problemas de conexões

Sintoma Verificação
Resolução de nomes ou falha TLS Verifique o host, o caminho DNS liberado, o modo TLS, a orientação do certificado e o clock do cliente.
Falha na autenticação Confirme que você é o criador do banco de dados e, em seguida, verifique o tenant, o público ou escopo, o formato do usuário e a expiração do token.
Falha de autorização após a autenticação Inspecione os privilégios efetivos do banco de dados e verifique se a operação é suportada.
A conexão fica em espera após um período de inatividade O banco de dados pode estar retomando a operação. Use retentativa limitada e inspecione o estado do item.
A conexão cai durante uma transição Abra uma nova conexão e tente novamente toda a transação com segurança, se for apropriado.
O portal funciona, mas um cliente externo falha Compare as configurações de endpoint, banco de dados, usuário, fluxo de token e TLS.
Endpoint de SQL Analytics rejeita escritas Migre para o endpoint do PostgreSQL.