pgcli, el cliente PostgreSQL que te hará olvidar psql

Llevo años usando psql. Años. Y no me malinterpretes, psql es un cliente soberbio y fiable. Pero tiene un problema que te rompe el día a día cuando trabajas con bases de datos con decenas de tablas y columnas. El autocompletado es básico, el resaltado de sintaxis brilla por su ausencia y acabas haciendo \dt cada dos por tres para recordar cómo se llamaba esa tabla de migrations. O peor, escribiendo SELECT * y luego buscando a mano los nombres de las columnas porque no te acuerdas de cuál era user_created_at y cuál user_updated_at. Y cuando finalmente encuentras la columna, te das cuenta de que has escrito mal el nombre y tienes que volver a empezar. Es un desgaste constante, pequeñas fricciones que se acumulan.

Hasta que descubrí pgcli, y desde entonces no he vuelto a mirar atrás. El cambio no fue inmediato, al principio lo usaba en paralelo, por si acaso. Pero a los dos días ya había borrado psql de mi alias mental. El veredicto rápido: si trabajas con PostgreSQL a diario y quieres ser más productivo, pgcli es para ti. Si solo entras una vez al mes a hacer un SELECT simple, quédate con psql, que para eso pesa menos y arranca al instante. Pero si escribes consultas todos los días, si pasas más tiempo en la terminal que en el navegador, esto te va a cambiar la vida.

¿Qué es pgcli?

Pues no es ni más ni menos que un cliente PostgreSQL con esteroides. Escrito en Python, con licencia BSD 3-Clause, y cerca de 13.300 estrellas en GitHub. Forma parte de la familia dbcli, la misma que ha dado mycli para MySQL y litecli para SQLite. La versión actual es la 4.5.0 (junio de 2026).

Especificación	Valor
Lenguaje	Python
Licencia	BSD 3-Clause
Estrellas GitHub	~13.300
Versión actual	4.5.0 (junio 2026)
Dependencias clave	prompt_toolkit, psycopg 3, Pygments, sqlparse
Familia	dbcli (mycli, litecli)
SO	Linux, macOS, Windows

Está construido sobre cuatro pilares. prompt_toolkit para la interfaz interactiva, Pygments para el resaltado, psycopg 3 para la conexión a PostgreSQL y sqlparse para analizar y entender las consultas. Esto último es clave, porque pgcli no se limita a completar palabras, entiende el contexto de lo que estás escribiendo.

Cómo funciona por dentro

La arquitectura de pgcli es más interesante de lo que parece a simple vista. Es una pieza de ingeniería bien pensada que va mucho más allá de un simple wrapper de psql con colores.

prompt_toolkit es la columna vertebral. Es una biblioteca Python para construir REPLs interactivos que soporta autocompletado, historial, atajos de teclado personalizados y manejo de terminal. Sin ella, pgcli no sería más que un script de Python feo. Con ella, tienes un shell con calidad de producción. Es la misma biblioteca que usa ipython o aws-shell, así que imagina el nivel. Soporta vi mode, emacs mode, mouse support, y hasta syntax highlighting en tiempo real mientras escribes.

psycopg 3 es el conector PostgreSQL. La versión 3 es una reescritura completa que ofrece conexiones asíncronas, type casting inteligente y soporte para PostgreSQL 16 y 17. pgcli lo usa para todo: desde enumerar tablas hasta ejecutar tus consultas. Una de las mejoras de psycopg 3 es que maneja mucho mejor los errores de conexión y la reconexión automática, algo que agradeces cuando el servidor se cae a media sesión.

sqlparse es la pieza más infravalorada. Es un analizador sintáctico de SQL que no solo entiende la estructura de las consultas, sino que puede decirte en qué contexto estás escribiendo. ¿Estás después de un FROM? Te muestra tablas. ¿Después de un JOIN? Te muestra las columnas que podrían formar parte de la condición. ¿Dentro de una CTE? También funciona. ¿Después de un GROUP BY? Te sugiere las columnas que no están en funciones de agregación. sqlparse no valida el SQL, no te dice si la consulta es correcta, pero sabe dónde estás en cada momento. Y eso es suficiente para hacer un autocompletado que parece magia.

Pygments se encarga del resaltado de sintaxis. Soporta 23 temas diferentes y entiende la estructura del SQL, coloreando palabras clave, funciones, strings y números de forma correcta. Si eres de los que cambia de tema cada semana, puedes configurarlo sobre la marcha con \T theme_name sin salir de la sesión. Monokai, vim, xcode, friendly, native, el que más te guste.

El autocompletado es donde pgcli marca distancias. Es contextual, no se limita a mostrarte palabras por orden alfabético. Escribes SELECT * FROM, pulsas Tab y te muestra solo las tablas. Escribes WHERE y te muestra las columnas. Escribes JOIN y si tienes claves foráneas definidas, te completa el JOIN entero. Y todo esto funciona también dentro de subconsultas y CTE.

SELECT * FROM users JOIN orders ON <Tab> -- te sugiere users.id = orders.user_id

Pero hay más. El fuzzy matching te permite escribir djmi y que encuentre django_migrations. No hace falta que te acuerdes del nombre exacto, pgcli hace el trabajo sucio.

SELECT * FROM djmi -- Tab → django_migrations

El sistema de MRU (Most Recently Used) aprende de tus hábitos. Las tablas y columnas que usas más a menudo aparecen primero en las sugerencias. Y todo se refresca en segundo plano: cuando creas una tabla nueva, pgcli lo detecta sin que tengas que recargar nada.

¿Y el dichoso asterisco? Otra cosa que me volvía loco en psql. En pgcli, si tienes SELECT * FROM users y pones el cursor sobre el * y pulsas Tab, expande todas las columnas. Adiós a tener que mirar el esquema o hacer \d users. Si en algún momento el autocompletado te satura, pulsas F2 y lo desactivas al instante. Simple 😊

Instalación paso a paso

La instalación no puede ser más sencilla. En Ubuntu o Debian, directamente desde los repositorios:

sudo apt-get install pgcli

En Arch, como no podía ser de otra forma:

sudo pacman -S pgcli

En macOS, con Homebrew:

brew install pgcli

En Fedora o RHEL, con dnf:

sudo dnf install pgcli

En Alpine, con apk:

apk add pgcli

Pero si quieres hacerlo bien, aislado del sistema, mi recomendación es usar pipx. Así tienes pgcli en su propio entorno sin ensuciar el Python del sistema:

pipx install pgcli

La ventaja de pipx es que cada herramienta vive en su propio virtual environment. No hay conflictos de dependencias, no contaminas el Python del sistema, y actualizar es tan fácil como pipx upgrade pgcli. Si no tienes pipx instalado, puedes hacerlo con pip install pipx o con tu gestor de paquetes. En Ubuntu, sudo apt install pipx.

Si eres de los que prefiere el método clásico, siempre puedes usar pip:

pip install pgcli

Pero ojo, esto instala pgcli en el Python del sistema o en el virtual environment que tengas activo. Si luego mezclas proyectos con diferentes versiones de psycopg, puedes acabar con conflictos. Por eso recomiendo pipx.

Y si te gusta lo último en herramientas Python, también puedes probar con uvx:

uvx pgcli

uvx es el ejecutor de uv, el gestor de paquetes Python escrito en Rust. Arranca pgcli al instante sin necesidad de instalación previa. Es ideal para probar versiones o para entornos CI donde no quieres instalar nada permanente.

Una vez instalado, verifica que todo funciona:

pgcli --version

Deberías ver algo como pgcli 4.5.0. Si no, revisa que tienes Python 3.10 o superior. Las dependencias clave se instalan automáticamente, pero vale la pena saber que necesitas prompt_toolkit>=3.0, psycopg>=3.1, Pygments>=2.10 y sqlparse>=0.4.

Para actualizar a la última versión, si usaste pipx:

pipx upgrade pgcli

Si usaste pip:

pip install --upgrade pgcli

Y si tienes dudas de qué versión tienes y qué hay nuevo, siempre puedes consultar el changelog en el repositorio de GitHub.

Conexión

Una vez instalado, conectarte es trivial. Puedes usar los parámetros clásicos:

pgcli -h localhost -p 5432 -U usuario basedatos

O la URI de conexión:

pgcli postgresql://usuario:pass@localhost:5432/mi_bd

También puedes usar variables de entorno, que es lo que hago yo en los entornos de producción. Así no tengo contraseñas en el historial del shell:

export PGHOST=localhost export PGPORT=5432 export PGUSER=usuario export PGDATABASE=mi_bd pgcli

Y si quieres evitar que la contraseña aparezca en el historial, puedes usar ~/.pgpass o activar el keyring. El archivo ~/.pgpass tiene el formato clásico de PostgreSQL: hostname:port:database:username:password. pgcli lo lee automáticamente si existe.

Pero donde pgcli marca la diferencia es con los alias DSN. Puedes definir conexiones en tu ~/.pgclirc y conectarte con un nombre. Adiós a recordar IPs, puertos y nombres de base de datos.

[alias_dsn] local = postgresql://user@localhost:5432/mydb prod = postgresql://admin@prod-server:5432/mydb

Y luego simplemente:

pgcli -D local pgcli -D prod

También soporta el archivo pg_service.conf de PostgreSQL. Si ya tienes definido un servicio así:

[mi-servicio] host=localhost port=5432 dbname=mydb user=usuario

Puedes conectarte con pgcli service=mi-servicio. pgcli lee pg_service.conf automáticamente desde las rutas estándar.

Desde la versión 3.4.0, pgcli incluye SSH tunnels automáticos. Si defines un host que solo es accesible por SSH, pgcli puede abrir el túnel él solito. Ya no hace falta andar con ssh -L 5432:localhost:5432 usuario@servidor manual antes de conectar. En el alias DSN puedes especificar el host SSH y pgcli se encarga de todo:

[alias_dsn] remoto = postgresql://user@db-interno:5432/mydb?sshtunnel=user@bastion.example.com:22

Y el modo --ping es otro detallazo. Comprueba si el servidor responde antes de lanzar la sesión interactiva, como un pg_isready pero integrado:

pgcli --ping -D prod

Si el servidor no responde, te dice el error antes de intentar abrir la sesión. Te ahorras esos segundos de espera cuando sabes que la VPN no está conectada.

Casos de uso avanzados

Aquí es donde pgcli se sale. Tiene funcionalidades que te cambian el día a día, mucho más que un psql con colores.

Monitoring con

El comando \watch es una pasada. Lanzas una consulta, pones \watch 5 y se ejecuta cada 5 segundos. Ideal para monitorizar procesos, bloqueos o el progreso de una operación larga.

SELECT pid, state, wait_event, query FROM pg_stat_activity WHERE state = 'active'; \watch 3

Lo uso mucho cuando estoy haciendo migraciones largas o cuando quiero ver si un proceso se ha desbloqueado. Te ahorra estar repitiendo la misma consulta como un autómata. También lo combino con \timing para ver cómo evolucionan los tiempos de ejecución de una consulta mientras optimizo índices.

EXPLAIN con F5

Pulsas F5 y la siguiente consulta que ejecutes te muestra el plan de ejecución formateado y legible, sin tener que escribir EXPLAIN ANALYZE manualmente. Lo vuelves a pulsar y vuelve al modo normal. Es tan sencillo como útil. Cuando estás optimizando consultas, esto te ahorra un montón de tecleo. Y lo mejor es que el formato de salida de pgcli hace el plan de ejecución mucho más legible que el de psql, con colores y sangrado.

y

El comando \timing activa el cronómetro. Cada consulta te muestra cuánto ha tardado. Imprescindible cuando estás comparando índices o reescribiendo consultas para ver si mejoran.

\timing SELECT COUNT(*) FROM orders WHERE status = 'pending'; -- Time: 0.423s

Y el \x para expanded output cuando una consulta tiene muchas columnas. Pero con auto_vertical = True en la configuración, pgcli lo hace solo cuando la terminal no da abasto. Te ahorras acordarte de escribirlo.

Named Queries con parámetros

Esta es una de esas características que no sabes que necesitas hasta que las pruebas. Puedes guardar consultas recurrentes con un nombre y ejecutarlas con un par de teclas.

\ns user_by_name SELECT * FROM users WHERE name = '$1' \ns count_active SELECT COUNT(*) FROM users WHERE active = $1 \ns search_logs SELECT * FROM logs WHERE message ILIKE '$*' \ns monthly_report SELECT date_trunc('month', created_at) AS mes, COUNT(*) AS total FROM orders WHERE created_at >= '$1' GROUP BY mes ORDER BY mes

Y luego ejecutas:

\n user_by_name "Skelly McDermott" \n count_active true \n search_logs %error% \n monthly_report 2026-01-01

El sistema de comandos es muy intuitivo. Las consultas se guardan en ~/.config/pgcli/named_queries.json y puedes editarlas a mano si quieres. Son persistentes entre sesiones y las tienes siempre disponibles.

\ns nombre consulta — guardar
\n — listar todas las guardadas
\n nombre — ejecutar
\nd nombre — eliminar

Soporta parámetros posicionales con $1, $2 para argumentos individuales, y $* o $@ para pasar todo lo que escribas. Es como tener un mini gestor de consultas favoritas integrado en el terminal, sin necesidad de herramientas externas ni GUIs.

Exportar a diferentes formatos

Además del clásico formato psql, puedes usar grid, fancy_grid, csv, tsv, html, markdown (GitHub), json, etc. Muy útil cuando necesitas pegar resultados en un informe o compartirlos.

pgcli -D local -c "SELECT * FROM users" --table-format markdown pgcli -D local -c "SELECT id, name FROM products" --table-format json pgcli -D local -c "SELECT * FROM logs" --table-format csv > logs.csv

El formato markdown es ideal para documentación. El csv para análisis en Excel o Google Sheets. Y el json para cuando necesitas meter los datos en una API. Un comando, un pipe y listo. También puedes cambiar el formato sobre la marcha dentro de la sesión interactiva con \T:

\T json SELECT * FROM users LIMIT 2; \T markdown SELECT * FROM users LIMIT 2;

Destructive warnings

Por defecto, pgcli te avisa antes de ejecutar un DROP, DELETE o TRUNCATE. Si eres de los que ha borrado una tabla por accidente (vamos, todos), agradecerás este aviso. Se configura con warn = True en el config. Cuando ejecutas un comando peligroso, pgcli te pide confirmación antes de seguir. Es ese seguro que no sabes que necesitas hasta que el seguro te salva el día.

Automatización con -c

Para scripts y automatización, el flag -c te permite ejecutar una consulta y salir:

pgcli -D local -c "VACUUM ANALYZE;" -c "SELECT now();"

Vale, no es tan potente como un script de psql, pero para tareas rápidas en cron o en pipelines de CI/CD, va de lujo. También puedes combinar varios flags -c para ejecutar múltiples consultas en una sola conexión.

Fish-style autosuggestions

Igual que en el shell Fish, pgcli te muestra en gris sugerencias basadas en tu historial mientras escribes. Pulsas flecha derecha y completas. Parece una tontería, pero cuando repites consultas parecidas, te ahorras un montón de tecleo. Es de esas cosas que no sabes que echas de menos hasta que las pierdes. Y si el historial se te hace pesado, puedes controlar su tamaño con history_size en la configuración.

Keyring para contraseñas seguras

Las contraseñas se guardan en el llavero del sistema, no en texto plano. Si activas keyring = True en el archivo de configuración, solo introduces la contraseña una vez y pgcli se encarga del resto. Usa el sistema de keyring de tu SO: GNOME Keyring, KDE Wallet, macOS Keychain o el que tengas. Seguro que tu contraseña de producción no debería estar en un archivo de texto plano, ¿verdad? La primera vez que te conectes, pgcli te preguntará si quieres guardarla en el llavero. Después de eso, ni te acordarás de que existe.

23 temas de sintaxis

Monokai, vim, xcode, friendly, native, dracula, solarized, material… el que más te guste. Lo configuras con syntax_style en el archivo de configuración y listo. Y si te cansas, puedes cambiarlo sobre la marcha sin salir de la sesión con \T nombre_tema. Es un detalle, pero cuando pasas ocho horas al día en la terminal, los detalles importan.

Configuración

El archivo de configuración está en ~/.config/pgcli/config en Linux. Si no existe, lo creas y pgcli lo lee automáticamente. Aquí te dejo el ejemplo completo con las opciones que uso en mi día a día.

Las opciones clave que te recomiendo ajustar:

smart_completion = True — el autocompletado contextual, no lo desactives
fuzzy_completion = True — el fuzzy matching que te salva cuando no recuerdas el nombre exacto
syntax_style = monokai — porque el código bien coloreado se lee mejor
timing = True — saber cuánto tarda cada consulta te hace mejor profesional
warn = True — porque todos hemos borrado algo sin querer
auto_vertical = True — para que las queries anchas no te rompan la vista
keyring = True — contraseñas seguras sin pensar

pgcli vs psql

Vamos a ser honestos. pgcli no es perfecto, y psql tampoco. Cada uno tiene su sitio. Aquí tienes una comparativa directa para que decidas tú mismo.

Característica	pgcli	psql
Autocompletado contextual	Sí, con fuzzy matching	Solo tablas básicas con Tab
Resaltado de sintaxis	23 temas	No
Named Queries	Sí, con parámetros	No
SSH tunnels integrados	Sí (v3.4.0+)	No
Exportar a múltiples formatos	CSV, JSON, MD, HTML, etc.	Solo COPY
Peso y dependencias	Python + 4 librerías	Incluido con PostgreSQL
Disponible en servidores mínimos	No (necesita Python)	Sí
Velocidad de arranque	~1-2 segundos	Instantáneo
Historial con autosuggestions	Sí (Fish-style)	No
Keyring	Sí	No
Temas y personalización	23 temas + colores	Solo colores básicos
Compatibilidad de comandos	, , , etc.	Todos
Edición multibuffer	No	Sí (con editor, múltiples buffers)
Scripting complejo	Básico (-c)	Potente (variables, condicionales, , )
Disponible sin instalar nada	No	Sí, viene con PostgreSQL

La conclusión es clara. pgcli gana en productividad del día a día: autocompletado, resaltado, consultas guardadas, exportación, keyring. Cada una de estas características te ahorra segundos, y los segundos se convierten en minutos, y los minutos en horas. En una sesión de ocho horas, la diferencia es abismal.

Pero psql tiene sus cartas. Es instantáneo. No necesita Python. Está en cualquier servidor que tenga PostgreSQL, por mínimo que sea. Y para scripting complejo, con variables, condicionales y redirección de salida, psql sigue siendo el rey. Si tienes que escribir un script de backup que se conecte a diez bases de datos y haga cosas raras, psql es tu herramienta.

Mi recomendación es que uses pgcli para tu sesión interactiva del día a día, y que tengas psql a mano para scripts y servidores mínimos. No es uno u otro, son complementarios.

Novedades de la 4.5.0

La versión actual trae algunas mejoras interesantes que merece la pena conocer. Soporte para Python 3.14, que ya está en las versiones nightly y prepara pgcli para el futuro. Si usas Python 3.14, no tendrás problemas de compatibilidad.

Cursor shape en modo vi. Si eres de los que usa vi en el terminal, ahora puedes tener beam, bloque o subrayado según el modo en que estés (insert o normal). Es un detalle, pero cuando estás alternando entre modos constantemente, saber de un vistazo en qué modo estás te ahorra errores.

Sugerencias para GROUP BY. El autocompletado ahora entiende que después de un GROUP BY necesitas las columnas que no están en funciones de agregación. Te las sugiere directamente. Si tienes una consulta con SELECT department, COUNT(*), AVG(salary) FROM employees GROUP BY, al pulsar Tab te sugiere department. Simple pero efectivo.

**Prompt escape . El nuevo \T en el prompt* muestra el estado de la transacción. Ideal para no perder el hilo cuando estás haciendo operaciones complejas con transacciones abiertas. Sabes si estás en BEGIN, COMMIT o en estado normal sin tener que mirar el historial.

Force-quit. Ctrl+C dos veces cuando tienes una transacción activa te saca de la sesión sin tener que hacer rollback manual. Es un salvavidas para cuando una transacción se ha quedado colgada y no quieres estar peleándote con el terminal.

Conclusión

Llegados a este punto, ¿qué conclusión he sacado? Pues que pgcli es de esas herramientas que, una vez pruebas, no entiendes cómo has podido vivir sin ellas. En productividad diaria no tiene rival, aunque no sea el wrapper más bonito ni el más ligero. Cada vez que pulsas Tab y te completa el nombre de una tabla, cada vez que ves el resaltado de sintaxis, cada vez que ejecutas una consulta guardada con dos teclas, te acuerdas de por qué lo instalaste.

Si buscas alternativas, la familia dbcli tiene mycli para MySQL y litecli para SQLite, con el mismo enfoque y la misma calidad. Si prefieres interfaces gráficas, DBeaver es una opción sólida, gratuita y multiplataforma que funciona con cualquier base de datos. Y DataGrip de JetBrains es el estándar de la industria si no te importa pagar por una experiencia más pulida.

Mi recomendación es que lo instales, lo pruebes una semana y vuelvas a psql. Verás que no puedes. La instalación es trivial, la curva de aprendizaje es prácticamente plana y la mejora en productividad es inmediata. Si trabajas con PostgreSQL a diario, te debes la oportunidad de probarlo. Una semana es suficiente para que te des cuenta de que no vas a volver atrás.

¿Y tú, has probado pgcli? ¿Sigues usando psql a pelo? Cuéntame en los comentarios si te animas a dar el salto o si conoces algún otro cliente de terminal que merezca la pena.

Más información,