Conexões e identidade

A extensão PostgreSQL para Visual Studio Code fornece uma caixa de diálogo de conexão que dá suporte a vários métodos de autenticação, criptografia SSL/TLS e ferramentas organizacionais, como grupos de servidores e conexões salvas. Este artigo aborda as principais tarefas de conexão: abrir a caixa de diálogo, escolher um método de autenticação, salvar e reutilização de conexões e organizar servidores.

Dica

Para túneis SSH, análise da cadeia de conexão ou configuração de arquivos de certificado, consulte Opções avançadas de conexão.

Abrir a janela de conexão

Você pode abrir a caixa de diálogo de conexão de várias maneiras:

  • Conexões: passe o mouse sobre o cabeçalho da seção Conexões e selecione Adicionar Nova Conexão (o + ícone).
  • Paleta de comandos: execute PGSQL: adicionar nova conexão.
  • Conexão salva ou recente: selecione um cartão de conexão na lista Conexões Salvas ou Conexões Recentes no painel lateral para carregar suas configurações na caixa de diálogo.

Quando você abre uma nova caixa de diálogo, o cabeçalho lê Nova Conexão e o título lê Conectar-se ao Servidor PostgreSQL. Quando você edita uma conexão existente, o cabeçalho é alterado para Editar Conexão.

Escolher um modo de entrada

As guias Connect via: na parte superior da caixa de diálogo permitem que você escolha como fornecer as informações de conexão:

Tab Descrição
Parâmetros Preencha campos individuais, como nome de servidor, tipo de autenticação, nome de usuário, senha, nome de banco de dados e nome de conexão. Esse é o modo padrão.
String de Conexão Cole uma cadeia de conexão em qualquer formato compatível. A extensão analisa a cadeia de caracteres e mostra o nome do servidor, o nome de usuário e o nome de banco de dados extraídos em um painel Detalhes da Conexão somente leitura.
Explorar o Azure Navegue diretamente por suas assinaturas do Azure, grupos de recursos e servidores para selecionar um servidor flexível do Banco de Dados do Azure para PostgreSQL ou um cluster do Azure HorizonDB (versão prévia). Requer uma conta do Azure conectada ao Visual Studio Code.

Todos os três modos compartilham os mesmos botões Salvar & Conectar e Testar Conexão na parte inferior da caixa de diálogo. O botão Avançado abre a gaveta Configurações avançadas de conexão em qualquer modo.

Preencher parâmetros de conexão

Quando você usa a guia Parâmetros, a caixa de diálogo apresenta os seguintes campos principais:

Campo Descrição
Nome do servidor Nome do host ou endereço IP do servidor PostgreSQL.
Tipo de Autenticação Método usado para autenticar. Veja Tipos de autenticação.
Nome de usuário Usuário ou função do banco de dados PostgreSQL. Visível quando o Tipo de Autenticação é Senha ou IAM do AWS (RDS/Aurora).
Senha Senha para a conta de usuário. Visível quando o Tipo de Autenticação é Senha.
Salvar Senha Marque esta caixa para armazenar a senha com segurança. Consulte o armazenamento de senhas.
Nome do banco de dados Nome do banco de dados ao qual se conectar. Deixe em branco para se conectar ao banco de dados padrão.
Nome da conexão Nome amigável opcional para essa conexão. A extensão exibe esse nome na árvore Conexões e na lista Conexões Salvas .

Campos adicionais são exibidos dependendo do tipo de autenticação. Para o Entra Auth, a caixa de diálogo mostra Entra Account, Entra Username e Tenant. Para o AWS IAM (RDS/Aurora), a caixa de diálogo mostra o Perfil do AWS e a Região do AWS.

Note

O campo Porta está localizado na gaveta Configurações avançadas de conexão sob as opções de nível superior. A porta padrão é 5432.

Tipos de autenticação

A lista suspensa Tipo de Autenticação oferece quatro opções.

Senha

A autenticação de senha é o método PostgreSQL padrão. Você fornece um nome de usuário e uma senha que o servidor valida em relação à configuração de autenticação (normalmente pg_hba.conf).

  1. Defina o tipo de autenticação como senha.
  2. Insira um nome de usuário e senha.
  3. Opcionalmente, selecione Salvar Senha para armazenar a senha com segurança.
  4. Selecione Salvar &conectar.

Armazenamento de senha

Quando você seleciona Salvar Senha, a extensão armazena a senha por meio da API Visual Studio CodeSecretStorage, que delega ao gerenciador de credenciais do sistema operacional:

  • macOS: conjunto de chaves
  • Windows: Gerenciador de Credenciais
  • Linux: libsecret (GNOME Keyring ou KWallet)

As senhas salvas são associadas à conexão específica e nunca são armazenadas em arquivos de configurações de texto sem formatação.

autenticação do Microsoft Entra

A autenticação do Microsoft Entra (anteriormente conhecido como Azure Active Directory) oferece autenticação sem senha baseada em token para o Servidor Flexível do Banco de Dados do Azure para PostgreSQL. A caixa de diálogo rotula essa opção Entra Auth.

Note

A autenticação Entra requer uma instância de servidor flexível do Banco de Dados do Azure para PostgreSQL com a autenticação Entra habilitada. Consulte o artigo sobre autenticação do Microsoft Entra no Banco de Dados do Azure para PostgreSQL para obter detalhes sobre a configuração.

Para se conectar com a autenticação do Entra:

  1. Adicione sua conta do Entra. Abra a Paleta de Comandos e execute PGSQL: Adicionar Microsoft Entra Conta. Entre com suas credenciais do Entra na janela do navegador que é aberta.
  2. Abra a caixa de diálogo de conexão. Defina o tipo de autenticação como Entra Auth.
  3. Selecione sua conta. Escolha a conta que você adicionou na lista suspensa Conta do Entra.
  4. Selecione um locatário. Se sua conta estiver vinculada a vários locatários, selecione o locatário apropriado na lista suspensa Locatário.
  5. Insira o nome de usuário do Entra. Digite o nome de usuário do Entra para a função do PostgreSQL mapeada à sua identidade.
  6. Conectar. Selecione Salvar &conectar. A extensão adquire um token de acesso e se autentica no servidor PostgreSQL em seu nome.

Os perfis de conexão salvos do Entra continuam a usar o valor herdado AzureMFA . O valor canônico bearer-token:entra-id é reservado para expedição controlada pelo servidor e migração de perfil futura.

Para remover uma conta do Entra, execute PGSQL: remova Microsoft Entra Conta da Paleta de Comandos e selecione a conta a ser removida. Para limpar os tokens armazenados em cache sem remover a conta, execute PGSQL: Clear cache de tokens da conta Microsoft Entra.

Modelo de conta dupla

A extensão dá suporte a um modelo de conta dupla para cenários de Azure. Você pode usar uma conta do Entra para autenticação de banco de dados e uma conta diferente para navegar Azure recursos (assinaturas, grupos de recursos e servidores).

  • O campo Conta Entra na caixa de diálogo da conexão controla qual identidade se autentica no banco de dados.
  • A guia Explorar o Azure usa a conta do Azure conectada ao Visual Studio Code (por meio da extensão Recursos do Azure) para enumerar assinaturas e recursos.

Dica

Essa separação é útil quando sua conta de administrador de banco de dados difere da conta que gerencia Azure assinaturas. Configure cada uma de forma independente para usar as permissões corretas para cada tarefa.

AWS IAM (RDS/Aurora)

A autenticação IAM do AWS usa um token de autenticação de banco de dados assinado pela AWS em vez de uma senha armazenada. Use esta opção somente para endpoints de banco de dados do Amazon RDS for PostgreSQL ou do Amazon Aurora PostgreSQL com a autenticação de banco de dados do IAM habilitada. Uma Região da AWS inserida manualmente pode complementar a inferência de região, mas isso não torna hosts PostgreSQL personalizados, hosts não RDS ou aliases CNAME suportados. A caixa de diálogo rotula essa opção AWS IAM (RDS/Aurora).

Note

Sua função de banco de dados PostgreSQL deve existir no servidor e deve ter permissão para usar a autenticação de banco de dados IAM. Para RDS e Aurora PostgreSQL, conceda a função rds_iam. Para obter mais informações, consulte a autenticação de banco de dados IAM para MariaDB, MySQL e PostgreSQL.

Para se conectar com a autenticação IAM do AWS:

  1. Prepare as credenciais da AWS. Configure o fluxo da CLI do AWS exigido pela sua organização. Exemplos incluem aws configure, aws sso login --profile <profile>ou uma configuração específica credential_process da organização.
  2. Abra a caixa de diálogo de conexão. Defina o tipo de autenticação como AWS IAM (RDS/Aurora).
  3. Insira o endpoint do servidor. Use o endpoint do Amazon RDS ou do Aurora PostgreSQL em Server name.
  4. Insira a função de banco de dados. No nome de usuário, insira o usuário ou a função do banco de dados PostgreSQL. Este não é o Perfil do AWS, o usuário do IAM, a função IAM ou o ARN.
  5. Escolha a origem da credencial do AWS. Selecione ou insira um perfil do AWS. Deixe o Perfil do AWS em branco para usar a cadeia de credenciais padrão do AWS.
  6. Defina a região do AWS, se necessário. A extensão infere a região dos nomes de host padrão RDS e Aurora quando possível. Se o nome do host não incluir a região, insira-a na Região do AWS.
  7. Conectar. Selecione Salvar &conectar. A extensão assina um token de autenticação de curta duração e o usa como a senha postgreSQL para a nova conexão.

A cadeia de credenciais da AWS dá suporte a variáveis de ambiente, arquivos compartilhados de configuração e credenciais do AWS, perfis de SSO do AWS e credential_process perfis. Ele não usa credenciais de metadados de instâncias do EC2 ou contêineres do ECS, e não usa cadeias de perfis baseadas em metadados credential_source.

Os tokens de autenticação de banco de dados IAM do AWS são válidos por 15 minutos. A extensão obtém novos tokens conforme necessário, enquanto as credenciais AWS subjacentes permanecem válidas. Não são necessárias etapas manuais de atualização de token.

Nenhum

Nenhum ignora totalmente a autenticação. A extensão se conecta sem enviar credenciais. Essa opção se aplica aos servidores PostgreSQL configurados com trust autenticação ou configurações similares sem credencial.

Conectar, testar e desconectar

Depois de preencher os detalhes da conexão, use as ações na caixa de diálogo de conexão e na árvore Conexões para salvar o perfil, conectar, editar ou remover servidores.

Salvar & Conectar

Depois de preencher os detalhes da conexão, selecione Salvar &conectar para estabelecer a conexão. Este botão executa duas ações:

  1. Salva a conexão como um perfil nas configurações do VS Code.
  2. Conecta-se ao servidor.

Se a conexão for bem-sucedida, o servidor aparecerá na árvore Conexões . A conexão também aparece nas listas Conexões Salvas e Conexões Recentes na caixa de diálogo de conexão.

Teste a conexão

Selecione Testar Conexão para verificar os parâmetros de conexão sem salvar o perfil ou adicionar o servidor à árvore Conexões . O botão mostra um spinner enquanto o teste é executado e, em seguida, exibe uma marca de seleção no êxito ou um ícone de aviso sobre falha.

Desligar

Para se desconectar de um servidor:

  • Conexões: clique com o botão direito do mouse no nó do servidor e selecione Desconectar.
  • Paleta de comandos: execute PGSQL: Desconectar.

Editar uma conexão existente

Para editar uma conexão salva, clique com o botão direito do mouse no servidor na árvore Conexões e selecione Editar Conexão. A caixa de diálogo de conexão é aberta no modo de edição com o cabeçalho Editar Conexão e o nome do perfil atual como o título. Faça suas alterações e selecione Salvar &conectar para se reconectar com as configurações atualizadas.

Configurações avançadas de conexão

Selecione o botão Avançado abaixo dos campos principais para abrir a gaveta Configurações avançadas de conexão . A gaveta contém:

  • Opções de nível superior: Escopo (usuário ou workspace), porta, nome do aplicativo, tempo limite de conexão e failover de várias sub-redes.
  • Seções agrupadas: seções recolhíveis em acordeão para Fonte, Segurança, Servidor, Cliente, SSL, Copilot e Túnel SSH.

A opção Escopo controla em que local o perfil de conexão é salvo:

Scope Onde o perfil é armazenado
User Configurações de usuário do VS Code (globais, disponíveis em qualquer área de trabalho)
Workspace Configurações do workspace do VS Code (compartilhadas com colaboradores por meio .vscode/settings.json)

Para obter detalhes de configuração de túnel SSL e SSH, consulte Opções avançadas de conexão.

Modo de acesso Copilot por conexão

A seção Copilot no painel avançado inclui uma lista suspensa Modo de acesso do Copilot com três opções:

Opção Efeito
Usar Configuração Global Herda o valor global pgsql.copilot.accessMode .
Somente leitura Restringe o Copilot a operações de somente leitura nessa conexão.
Leitura/Escrita Permite que Copilot execute operações de leitura e gravação nessa conexão.

SSL e TLS

O SSL/TLS criptografa a conexão entre Visual Studio Code e seu servidor PostgreSQL. Configure o modo SSL na seção SSL da gaveta Configurações avançadas de conexão ou em seu cadeia de conexão.

Modos SSL

Mode Descrição
Desabilitar Nenhuma criptografia SSL. A conexão não está criptografada.
Permitir Tenta uma conexão não criptografada primeiro; retornará ao SSL se o servidor exigir.
Preferir Tenta o SSL primeiro; retornará a uma conexão não criptografada se a negociação SSL falhar. Esse é o padrão para muitos clientes PostgreSQL.
Exigir Requer criptografia SSL, mas não verifica o certificado do servidor. Protege contra interceptações passivas.
Verify-CA Requer SSL e verifica se o certificado do servidor é assinado por uma AC (autoridade de certificação) confiável.
Verificação completa Exige SSL, verifica a autoridade certificadora e confere se o nome do host do servidor corresponde ao Common Name (CN) ou ao Subject Alternative Name (SAN) do certificado. Fornece a proteção mais forte.

Note

Banco de Dados do Azure para PostgreSQL requer SSL por padrão. Use Require na maioria dos cenários ou Verify-Full com o certificado DigiCert Global Root G2 para obter o máximo de segurança.

Dica

Para configuração de arquivo de certificado e cenários de TLS mútuos, consulte opções de conexão avançada.

Gerenciar conexões salvas e recentes

A caixa de diálogo de conexão inclui um painel lateral com duas listas:

  • Conexões salvas: conexões que você salvou anteriormente com Save &Connect. Cada cartão mostra o nome de exibição do servidor. Passe o mouse sobre um cartão para revelar um botão excluir. Selecione um cartão para carregar suas configurações na caixa de diálogo.
  • Conexões recentes: conexões que você usou recentemente, independentemente de tê-las salvado com um Nome de Conexão. Passe o mouse para exibir um botão para remover.

A lista Conexões Recentes é limitada pela configuração pgsql.maxRecentConnections . O número máximo de conexões abertas simultâneas por perfil e banco de dados é controlado pela pgsql.maxConnections configuração (padrão: 10).

Grupos de servidores

Os grupos de servidores ajudam você a organizar conexões na árvore Conexões . Você pode atribuir um nome e uma cor personalizados a cada grupo, facilitando a identificação de ambientes como Desenvolvimento, Preparo e Produção rapidamente.

Criar um grupo de servidores

  1. Clique com o botão direito do mouse na árvore Conexões e selecione Criar Grupo de Servidores.
  2. Na caixa de diálogo, insira um Nome, descrição opcional e selecione uma Cor para o grupo.

Editar ou remover um grupo de servidores

  • Editar: clique com o botão direito do mouse em um grupo de servidores na árvore Conexões e selecione Editar Grupo de Servidores para alterar seu nome, descrição ou cor.
  • Remover: clique com o botão direito do mouse em um grupo de servidores e selecione Remover. As conexões no grupo não são excluídas; eles se movem para o grupo padrão.

Atribuir uma conexão a um grupo

Quando você cria ou edita uma conexão, a caixa de diálogo de conexão inclui uma lista suspensa grupo de servidores na área de campos principais. Selecione um grupo na lista para atribuir a conexão a esse grupo.

As cores do grupo aparecem como uma barra colorida ao lado do nome do grupo na árvore Conexões , fornecendo identificação visual rápida.

metadados Azure

Quando você se conecta a um servidor Banco de Dados do Azure para PostgreSQL flexível, a caixa de diálogo de conexão pode exibir um painel de metadados Azure junto com o formulário. Este painel mostra a Assinatura e o Grupo de Recursos do servidor depois que você seleciona Buscar metadados do Azure. A inclusão de metadados Azure permite recursos de gerenciamento, como o painel do servidor e as métricas de Azure Monitor.

Solucionar problemas comuns de conexão

Quando uma tentativa de conexão falha, a causa geralmente é uma configuração de rede, autenticação ou SSL. As seções a seguir abrangem os casos mais comuns.

Conexão recusada ou tempo limite

Se a conexão falhar antes do início da autenticação, verifique o nome do servidor e a porta primeiro. Verifique se o PostgreSQL está em execução, se a porta pode ser acessada no computador e se as regras de firewall de rede permitem a conexão. Você pode ajustar o tempo limite de conexão na gaveta Configurações avançadas de conexão para permitir mais tempo para redes lentas.

Erros de validação de certificado ou SSL

Se o servidor exigir criptografia, confirme se o modo SSL selecionado na seção SSL da gaveta avançada corresponde à configuração do servidor. Para Verify-CA e Verify-Full, verifique se o certificado de autoridade de certificação correto está configurado. Para obter detalhes do arquivo de certificado, consulte opções de conexão avançada.

Problemas de entrada ou de token do Microsoft Entra

Se a autenticação do Entra falhar, confirme se o servidor flexível de destino do Banco de Dados do Azure para PostgreSQL está com a autenticação do Entra habilitada e, em seguida, verifique se você selecionou a conta e o tenant corretos na caixa de diálogo de conexão. Se necessário, execute PGSQL: remova Microsoft Entra Conta e adicione novamente a conta. Para redefinir os tokens armazenados em cache, execute PGSQL: Limpar o cache de tokens da conta do Microsoft Entra.

Problemas de perfil ou token do IAM da AWS

Se a autenticação do AWS IAM falhar, verifique se Server name é o endpoint do Amazon RDS ou do Aurora PostgreSQL, e não um nome de host personalizado ou um alias CNAME. Confirme se o nome de usuário é a função de banco de dados PostgreSQL e se a função tem a autenticação de banco de dados IAM habilitada no servidor. Verifique se o Perfil da AWS selecionado pode obter credenciais da AWS compatíveis; por exemplo, execute aws sts get-caller-identity --profile <profile> para um perfil nomeado ou omita --profile ao usar a cadeia de credenciais padrão. Se a inferência de região falhar em um endpoint com suporte, insira manualmente a AWS Region.

A análise de cadeia de conexão não preenche os campos certos

Se um cadeia de conexão colado não preencher os valores esperados, examine os padrões de entrada com suporte nas opções de conexão avançada. Se o formato de origem for incomum, alterne para a guia Parâmetros e insira os valores manualmente.

Conteúdo relacionado

  • Last updated on