Usar psql no terminal

A extensão PostgreSQL para o Visual Studio Code permite que você abra sessões do psql conectadas automaticamente aos seus bancos de dados e execute arquivos .sql por meio de psql. Você obtém acesso total aos recursos nativos psql , incluindo comandos de barra invertida, COPY fluxos de trabalho e scripts interativos, sem sair do editor.

A extensão passa os detalhes da conexão (host, porta, banco de dados, usuário e senha) automaticamente, para psql que você possa começar a trabalhar imediatamente após abrir uma sessão.

Pré-requisitos

Note

Se a extensão não puder localizar psql, ela mostrará uma notificação de erro com um link do Learn More para a página de downloads do PostgreSQL. Você também pode apontar a extensão para um local de instalação personalizado com a pgsql.pgBinaryDirs configuração. Consulte Configurar o caminho binário psql.

Escolher entre psql e o editor de consultas

A maioria dos fluxos de trabalho do PostgreSQL usa ambas as ferramentas em momentos diferentes:

Tool Melhor para
Editor de consultas e IntelliSense IntelliSense, resultados em formato gráfico, gráficos, histórico de consultas e exportação de resultados.
psql Terminal Comandos de barra invertida, execução de scripts nativos, fluxos de trabalho com \copy e solução de problemas no terminal.

Abrir um terminal conectado

Abra uma psql sessão conectada automaticamente a um banco de dados específico. A extensão inicia psql com os sinalizadores -h, -p, -d e -U e define a variável de ambiente PGPASSWORD, para que você não precise inserir os detalhes da conexão manualmente.

  1. Na árvore Conexões , clique com o botão direito do mouse em um nó de banco de dados.
  2. Selecione Conectar com PSQL.

Um terminal de tarefas do Visual Studio Code é aberto com psql conectado ao banco de dados selecionado. A guia terminal é chamada PSQL: <nome> do perfil.

Você também pode executar esse comando na Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P): pesquise PGSQL: Conecte-se ao PSQL.

Note

Para conexões com o Banco de Dados do Azure para PostgreSQL que usam autenticação do Microsoft Entra ID, a extensão valida o token de autenticação antes de iniciar psql e passa o token como senha. Sua sessão permanece conectada sem autenticação manual.

Executar um arquivo SQL

Execute um arquivo .sql por meio de psql, usando a conexão do editor ativo. A saída aparece em um terminal de tarefas Visual Studio Code.

  1. Abra um .sql arquivo no editor.
  2. Conecte o editor a um banco de dados se ele ainda não estiver conectado.
  3. Clique com o botão direito do mouse no editor e selecione Executar arquivo com PSQL.

A extensão salva o arquivo e, em seguida, executa psql -f <filepath> na conexão ativa. Um terminal de tarefas é aberto para mostrar a saída de execução. O diretório de trabalho é definido como a pasta que contém o arquivo, portanto, caminhos relativos no script são resolvidos corretamente.

Importante

Salve o arquivo antes da execução. Se as alterações não salvas não puderem ser salvas, a extensão mostrará uma mensagem informando que o arquivo deve ser salvo antes de executar comandos PSQL. A operação é cancelada.

Configurar o caminho binário psql

A extensão pesquisa psql em três locais, nesta ordem:

  1. Binários agrupados: ferramentas de cliente postgreSQL que são enviadas com a extensão, organizadas por versão.
  2. PATH do sistema: diretórios listados na variável de ambiente PATH do seu sistema operacional.
  3. Diretórios personalizados: caminhos que você adiciona à pgsql.pgBinaryDirs configuração.

Quando várias versões de psql são encontradas, a extensão seleciona a versão que melhor corresponde à versão do PostgreSQL do seu servidor. Se nenhuma correspondência exata existir, ela usará a versão mais próxima disponível.

Para adicionar um diretório binário personalizado:

  1. Abrir Configurações (Ctrl+, / Cmd+,).
  2. Pesquise por pgsql.pgBinaryDirs.
  3. Selecione Adicionar Item e insira o caminho absoluto para o diretório que contém o psql binário.
  4. Reinicie Visual Studio Code para que a alteração entre em vigor.

Dica

No macOS com Homebrew, o caminho típico é /opt/homebrew/opt/postgresql@17/bin. No Windows, geralmente é C:\Program Files\PostgreSQL\17\bin.

Como a extensão inicia o psql

Quando você seleciona Conectar com PSQL ou Executar arquivo com PSQL, a extensão monta a psql invocação da seguinte maneira:

Detalhes da conexão Como a extensão transmite isso
Host (-h) Do endereço do servidor no perfil de conexão.
Porta (-p) Na porta do perfil de conexão. O padrão é 5432.
Banco de dados (-d) O nó de banco de dados selecionado ou o banco de dados padrão do perfil de conexão
Usuário (-U) O nome de usuário do perfil de conexão; para Microsoft Entra ID, o nome de usuário ou o endereço de email do Entra
Senha Definido por meio da variável de ambiente PGPASSWORD; para o Microsoft Entra ID, o token de acesso renovado
Codificação do cliente Definido por meio da variável de ambiente PGCLIENTENCODING (o valor padrão é UTF8)

A extensão é executada psql como uma tarefa Visual Studio Code, que é aberta no painel Terminal. O terminal da tarefa permanece aberto após o encerramento de psql para que você possa revisar a saída.

Casos de uso

O psql terminal é útil quando você precisa de recursos além do editor de consultas interno:

  • Sessões interativas do SQL: execute comandos ad hoc e inspecione os resultados em um ambiente familiar psql .
  • Importação/exportação de dados em massa: use os comandos \copy ou COPY para carregamento de dados com alto desempenho.
  • Tarefas administrativas: gerenciar funções, permissões e configuração de servidor com acesso total psql .
  • Teste de script: validar .sql scripts em nativos psql antes de implantá-los.
  • Comandos de barra invertida: Use \dt, \d+, \timing, \x e outros comandos que não estão disponíveis no editor gráfico de consultas.

Tarefas comuns psql

Inspecionar objetos de banco de dados

Use psql comandos de barra invertida para inspecionar rapidamente o schema:

\dt
\d+ public.orders
\dn

Esses comandos listam tabelas, mostram definições de objeto detalhadas e esquemas de lista.

Ative a temporização e a saída expandida

\timing on
\x on
SELECT * FROM public.orders LIMIT 5;

\timing exibe a duração da consulta após cada instrução. A saída expandida (\x) facilita a leitura de linhas largas.

Carregar ou exportar dados com \copy

\copy public.customers FROM '/Users/example/customers.csv' WITH (FORMAT csv, HEADER true)

Use \copy para importação ou exportação em massa via terminal, reutilizando o contexto de conexão gerenciado pela extensão.

Troubleshoot

psql não encontrado

Se a extensão mostrar o erro "Não foi possível localizar o executável psql", tente estas etapas:

  1. Instale as ferramentas de cliente postgreSQL para seu sistema operacional na página de downloads do PostgreSQL.
  2. Verifique se psql está disponível executando psql --version em um terminal do sistema.
  3. Se psql estiver instalado em um local diferente do padrão, adicione o diretório à pgsql.pgBinaryDirs configuração. Consulte Configurar o caminho binário psql.
  4. Reinicie Visual Studio Code.

Abrir uma pasta de workspace

A extensão requer uma pasta de workspace aberta para iniciar psql. Se uma mensagem disser que uma pasta do espaço de trabalho precisa estar aberta, abra uma pasta com Arquivo>Abrir Pasta e tente novamente.

Falhas de autenticação ou conexão

Se psql for aberta, mas a conexão falhar:

  • Confirme se o host, a porta e o banco de dados estão corretos no perfil de conexão. Consulte Conexões e identidade.
  • Para autenticação do Microsoft Entra ID, verifique se sua conta ainda está conectada. A extensão atualiza tokens automaticamente, mas sessões expiradas podem exigir autenticação.
  • Se você usar SSL ou um túnel SSH, teste novamente a mesma conexão na caixa de diálogo de conexão antes de reabrir psql.

As alterações de arquivo não são executadas

Quando você executa um arquivo com Executar arquivo com PSQL, a extensão salva o arquivo em disco antes de executá-lo. Se o salvamento falhar, a extensão cancelará a operação. Salve o arquivo corretamente antes de verificar o resultado.

Conteúdo relacionado

  • Last updated on