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.
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
Abra o banco de dados HorizonDB no portal Fabric.
Abra uma nova consulta SQL.
Executar:
SELECT current_database() AS database_name, current_user AS signed_in_user, pg_backend_pid() AS session_id, clock_timestamp() AS connected_at;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:
- Código do Visual Studio.
- A extensão PostgreSQL para Visual Studio Code, publicada pela Microsoft.
Abra a conexão a partir da barra de ferramentas Fabric:
Selecione Visual Studio Code. Se necessário, abra Mais opções (...) primeiro.
No painel de conexão, revise os pré-requisitos de instalação e os detalhes da conexão PostgreSQL.
Selecione Abrir no VS Code e permita o prompt de protocolo do
vscodenavegador.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.
Verifique o host, a porta e o banco de dados pré-preenchidos. O nome do banco de dados é
postgresna pré-visualização atual, e não o nome de exibição do item Fabric.Para Tipo de Autenticação, selecione Entra Auth.
Faça login como criador do banco de dados.
Digite um Nome de Conexão reconhecível e selecione Salvar e Conectar.
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.
- Defina um tempo limite de conexão finito.
- Tente novamente em caso de falhas de conexão retentáveis com backoff exponencial limitado e jitter.
- Abra uma nova conexão em vez de reutilizar uma que falhou.
- Tente novamente uma transação somente quando souber que ela não foi confirmada ou quando a operação for idempotente.
- 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. |