Conceptos básicos de psql

7 ejemplos para el uso diario de psql: 5 básicos y 2 intermedios.

Prerrequisitos

psql --version   # haz coincidir la versión principal con la del servidor cuando sea posible

• Instala postgresql-client-18 (o tu versión principal de destino) en las estaciones de trabajo de administración.
• Almacena los valores predeterminados de conexión en ~/.pgpass o en un gestor de secretos, no en el historial del shell.

Ejemplos básicos

1. Conectar a una base de datos

psql "postgresql://app_ro:****@db.internal:5432/myapp?sslmode=require"
# o
psql -h db.internal -p 5432 -U app_ro -d myapp

• sslmode=require aplica TLS en la conexión.
• Un nombre de base de datos incorrecto aún se conecta; podrías consultar silenciosamente el esquema incorrecto.
• Utiliza roles de solo lectura para consultas exploratorias en producción.

2. Cambiar de base de datos (\c)

\c myapp
\c myapp app_ro
\conninfo

• \c nombre_db [usuario] abre una nueva conexión en la misma sesión de psql.
• \conninfo imprime el host, el puerto y el usuario; verifica antes de realizar operaciones destructivas.
• La reconexión restablece las GUC de sesión como search_path a menos que se establezcan por rol.

Relacionado: Scripting con psql - ejecuciones no interactivas

3. Listar objetos (\dt, \d)

\dt public.*
\d+ orders
\dn
\df public.*

• \d+ añade el tamaño de almacenamiento y los comentarios de descripción.
• \dn lista los esquemas, algo fundamental en diseños multiinquilino.
• Los metacomandos consultan catálogos; respetan tu search_path actual.

4. Medir el tiempo de las consultas (\timing)

\timing on
SELECT count(*) FROM orders WHERE created_at > now() - interval '7 days';

• Muestra el tiempo de ejecución del servidor, no el tiempo de ida y vuelta de la red.
• Actívalo para cada investigación de rendimiento ad hoc.
• Combínalo con EXPLAIN (ANALYZE, BUFFERS) para obtener detalles a nivel de plan.

Relacionado: Reglas de índices y consultas - EXPLAIN antes de fusionar

5. Hábitos seguros con LIMIT

-- Siempre limita las SELECT exploratorias en tablas grandes
SELECT id, status, created_at
FROM orders
ORDER BY created_at DESC
LIMIT 50;
 
-- Evita escaneos completos accidentales
SELECT * FROM events LIMIT 100;  -- aún lee si no hay un plan optimizado para índices

• LIMIT sin ORDER BY devuelve una porción arbitraria.
• SELECT * en filas JSONB anchas transfiere megabytes por fila.
• Utiliza réplicas de lectura para la exploración de analistas cuando estén disponibles.

Ejemplos intermedios

6. Formatos de salida

\x on
SELECT * FROM pg_stat_activity WHERE pid = pg_backend_pid();
 
\a
\t
SELECT setting FROM pg_settings WHERE name = 'max_connections';

• La visualización expandida (\x) ayuda con las consultas de catálogos anchos.
• \a (desactivado) + \t (solo tuplas) = TSV amigable para scripts.
• \pset footer off elimina los recuentos de filas para el análisis por máquina.

7. Salvaguardas de sesión de solo lectura

BEGIN READ ONLY;
SELECT sum(amount) FROM payments WHERE paid_at >= current_date;
ROLLBACK;

# Conéctate explícitamente como rol de solo lectura
psql -U app_ro -d myapp -c "SELECT 1"

• BEGIN READ ONLY bloquea UPDATE accidentales en la misma transacción.
• Prefiere un rol sin INSERT/UPDATE/DELETE en producción.
• Algunos equipos crean un alias psql_prod='psql -U app_ro ...' solo en jump boxes aprobados.

Versiones de la pila: Esta página se escribió para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x y PostGIS 3.5+.