Uso de psql en el terminal

La extensión de PostgreSQL para Visual Studio Code te permite abrir sesiones de psql que se conectan automáticamente a tus bases de datos y ejecutar archivos .sql mediante psql. Tienes acceso completo a las funciones nativas de psql, incluidos los comandos con barra invertida, los flujos de trabajo de COPY y la creación interactiva de scripts, sin salir del editor.

La extensión pasa automáticamente los datos de conexión (host, puerto, base de datos, usuario y contraseña) a psql, para que pueda empezar a trabajar de inmediato después de abrir una sesión.

Prerequisites

Note

Si la extensión no puede encontrar psql, muestra una notificación de error con un vínculo Más información a la página de descargas de PostgreSQL. También puede indicar a la extensión una ubicación de instalación personalizada mediante la opción pgsql.pgBinaryDirs. Consulte Configuración de la ruta de acceso binaria de psql.

Elegir entre psql y el editor de consultas

La mayoría de los flujos de trabajo de PostgreSQL usan ambas herramientas en momentos diferentes:

Herramienta Más adecuado para
Editor de consultas e IntelliSense IntelliSense, resultados gráficos, gráficos, historial de consultas y exportación de resultados.
psql terminal Comandos con barra invertida, ejecución de scripts nativos, flujos de trabajo con \copy y resolución de problemas en el terminal.

Apertura de un terminal conectado

Abra una psql sesión que se conecte automáticamente a una base de datos específica. La extensión inicia psql con los indicadores -h, -p, -d y -U, y establece la variable de entorno PGPASSWORD, por lo que no es necesario introducir manualmente los datos de conexión.

  1. En el árbol Conexiones , haga clic con el botón derecho en un nodo de base de datos.
  2. Seleccione Conectar con PSQL.

Se abre un terminal de tareas de Visual Studio Code con psql conectado a la base de datos seleccionada. La pestaña terminal se denomina PSQL: <nombre> del perfil.

También puede ejecutar este comando desde la paleta de comandos (Ctrl+Shift+P / Cmd+Shift+P): busque PGSQL: Conectar con PSQL.

Note

Para las conexiones de Azure Database for PostgreSQL que usan la autenticación de Microsoft Entra ID, la extensión valida el token de autenticación antes de iniciar psql y pasa el token como contraseña. La sesión permanece conectada sin autenticación manual.

Ejecución de un archivo SQL

Ejecute un archivo .sql mediante la conexión de psql del editor activo. La salida aparece en un terminal de tareas de Visual Studio Code.

  1. Abra un .sql archivo en el editor.
  2. Conecte el editor a una base de datos si aún no está conectado.
  3. Haga clic con el botón derecho en el editor y seleccione Ejecutar archivo con PSQL.

La extensión guarda el archivo y, a continuación, ejecuta psql -f <filepath> con la conexión activa. Se abre un terminal de tareas para mostrar la salida de ejecución. El directorio de trabajo se establece en la carpeta que contiene el archivo, por lo que las rutas relativas en el script se resuelven correctamente.

Importante

Guarde el archivo antes de la ejecución. Si no se pueden guardar los cambios no guardados, la extensión muestra un mensaje que indica que el archivo debe guardarse antes de ejecutar comandos PSQL. La operación se cancela.

Configuración de la ruta de acceso binaria de psql

La extensión busca psql en tres ubicaciones, en este orden:

  1. Archivos binarios agrupados: herramientas de cliente de PostgreSQL que se incluyen con la extensión, organizada por versión.
  2. Ruta de acceso del sistema: directorios enumerados en la variable de entorno del PATH sistema operativo.
  3. Directorios personalizados: rutas de acceso que agregue a la pgsql.pgBinaryDirs configuración.

Cuando se encuentran varias versiones de psql , la extensión selecciona la versión que mejor coincide con la versión de PostgreSQL del servidor. Si no existe ninguna coincidencia exacta, usa la versión disponible más cercana.

Para agregar un directorio binario personalizado:

  1. Abra Configuración (Ctrl+, / Cmd+,).
  2. Busque pgsql.pgBinaryDirs.
  3. Seleccione Agregar elemento y escriba la ruta de acceso absoluta al directorio que contiene el psql binario.
  4. Reinicie Visual Studio Code para que el cambio surta efecto.

Tip

En macOS con Homebrew, la ruta de acceso típica es /opt/homebrew/opt/postgresql@17/bin. En Windows, normalmente es C:\Program Files\PostgreSQL\17\bin.

Cómo inicia la extensión psql

Al seleccionar Conectar con PSQL o Ejecutar archivo con PSQL, la extensión ensambla la invocación de la psql siguiente manera:

Detalles de la conexión Cómo la extensión la transmite
Anfitrión (-h) A partir de la dirección del servidor del perfil de conexión.
Puerto (-p) Desde el puerto del perfil de conexión. El valor predeterminado es 5432.
Base de datos (-d) El nodo de base de datos seleccionado o la base de datos predeterminada del perfil de conexión
Usuario (-U) Nombre de usuario del perfil de conexión; para Microsoft Entra ID, el nombre de usuario de Entra o la dirección de correo electrónico
Contraseña Se establece mediante la variable de entorno PGPASSWORD; para Microsoft Entra ID, el token de acceso renovado
Codificación de cliente Se establece mediante la variable de entorno PGCLIENTENCODING (por defecto: UTF8)

La extensión ejecuta psql como una tarea de Visual Studio Code, que se abre en el panel Terminal. El terminal de la tarea permanece abierto después de que salga psql para que puedas revisar la salida.

Casos de uso

El psql terminal es útil cuando necesita funcionalidades más allá del editor de consultas integrado:

  • Sesiones sql interactivas: ejecute comandos ad hoc e inspeccione los resultados en un entorno familiar psql .
  • Importación/exportación masiva de datos: Use los comandos \copy o COPY para la carga de datos de alto rendimiento.
  • Tareas administrativas: administre roles, permisos y configuración del servidor con acceso completo psql .
  • Pruebas de script: valide .sql los scripts en nativos psql antes de implementarlos.
  • Comandos con barra invertida: Utilice \dt, \d+, \timing, \x y otros comandos que no están disponibles en el editor gráfico de consultas.

Tareas comunes psql

Inspección de objetos de base de datos

Usa comandos con barra invertida psql para inspeccionar rápidamente el esquema:

\dt
\d+ public.orders
\dn

Estos comandos enumeran tablas, muestran definiciones de objetos detalladas y esquemas de lista.

Activar la sincronización y la salida expandida

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

\timing muestra la duración de la consulta después de cada sentencia. La salida expandida (\x) facilita la lectura de filas anchas.

Carga o exportación de datos con \copy

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

Usa \copy para operaciones masivas de importación o exportación orientadas al terminal, reutilizando el contexto de conexión administrado por la extensión.

Troubleshoot

psql no encontrado

Si la extensión muestra el error "No se pudo encontrar el archivo ejecutable psql", pruebe estos pasos:

  1. Instale las herramientas de cliente de PostgreSQL para el sistema operativo desde la página de descargas de PostgreSQL.
  2. Compruebe que psql está disponible mediante la ejecución psql --version en un terminal del sistema.
  3. Si psql está instalado en una ubicación no estándar, agregue el directorio a la pgsql.pgBinaryDirs configuración. Consulte Configuración de la ruta de acceso binaria de psql.
  4. Reinicie Visual Studio Code.

Abrir una carpeta del área de trabajo

La extensión requiere una carpeta de área de trabajo abierta para iniciar psql. Si un mensaje indica que debe haber una carpeta del área de trabajo abierta, abra una carpeta con Archivo>Abrir carpeta y, a continuación, vuelva a intentarlo.

Errores de autenticación o conexión

Si psql se abre, pero se produce un error en la conexión:

  • Confirme que el host, el puerto y la base de datos son correctos en el perfil de conexión. Consulte Conexiones e identidad.
  • Para la autenticación de Microsoft Entra ID, compruebe que su cuenta sigue con la sesión iniciada. La extensión actualiza los tokens automáticamente, pero las sesiones expiradas pueden requerir la reautenticación.
  • Si usa SSL o un túnel SSH, vuelva a probar la misma conexión desde el diálogo de conexión antes de volver a abrir psql.

Los cambios de archivo no se ejecutan

Al ejecutar un archivo con Run file with PSQL (Ejecutar archivo con PSQL), la extensión guarda el archivo en el disco antes de la ejecución. Si falla el guardado, la extensión cancela la operación. Guarde el archivo correctamente antes de revisar la salida.

Contenido relacionado

  • Last updated on