PostgreSQL
Instalación, conexión y herramientas
Guía para instalar PostgreSQL, conectarse con psql y clientes gráficos, gestionar servicios y entender cadenas de conexión y entornos locales.
- Última actualización
- Actualizada
- Nivel
- Fundamentos
PostgreSQL
Guía para instalar PostgreSQL, conectarse con psql y clientes gráficos, gestionar servicios y entender cadenas de conexión y entornos locales.
Instalar PostgreSQL, conectarse y operar una instancia son problemas distintos. Una conexión exitosa depende de que exista un servidor escuchando, una ruta de red válida, una database, un rol autorizado y un método de autenticación compatible.
Trabajar con PostgreSQL requiere separar cuatro piezas:
servidor PostgreSQL
→ proceso que escucha conexiones y administra databases
cliente
→ psql, una aplicación, un ORM o una interfaz gráfica
credenciales
→ rol, secreto o mecanismo de autenticación
canal
→ socket local, TCP y normalmente TLS en producciónInstalar psql solo instala un cliente. No significa que exista una instancia local. De la misma forma, tener un servidor activo no obliga a utilizar una interfaz gráfica: cualquier cliente compatible con el protocolo puede conectarse.
Muchos errores iniciales se diagnostican mal porque se confunden capas diferentes:
connection refused suele indicar que nadie escucha en el host o puerto.password authentication failed indica que la red funcionó, pero la autenticación falló.database does not exist significa que el servidor respondió, pero el destino lógico no existe.no pg_hba.conf entry indica que la política de acceso no permite esa combinación de origen, rol, database o cifrado.Comprender esta separación permite investigar el fallo en el orden correcto en lugar de cambiar contraseñas ante cualquier mensaje.
cliente
↓ resuelve host
red / socket local
↓ llega al puerto
postmaster acepta conexión
↓ consulta pg_hba.conf
método de autenticación
↓ verifica rol y secreto
abre backend process
↓ selecciona database
sesión listaCada conexión aceptada crea un backend process dedicado en la arquitectura tradicional de PostgreSQL. Ese proceso mantiene estado de sesión: transacción actual, parámetros, prepared statements, objetos temporales y permisos efectivos.
Es apropiado cuando quieres que el sistema administre servicio, rutas, usuario del sistema y actualizaciones.
Ventajas:
systemd o servicio equivalente.Costes:
Puede simplificar instalación en Windows o macOS y ofrecer herramientas adicionales. Debes seguir entendiendo dónde quedan data directory, logs y configuración.
docker run --name postgres-dev \
-e POSTGRES_PASSWORD=dev-password \
-e POSTGRES_DB=domisys \
-p 5432:5432 \
-v postgres-data:/var/lib/postgresql/data \
postgres:18Este comando:
Simplificaciones:
5432 no es necesario si solo otros contenedores usan la instancia.latest dificulta reproducibilidad.initdb crea un nuevo database cluster y su data directory. Arrancar el servidor reutiliza uno existente.
No ejecutes initdb sobre un directorio con datos que deseas conservar. Un cluster contiene catálogos, WAL, configuraciones y todas las databases de esa instancia.
postgresql://app_user:password@db.example.internal:5432/domisys?sslmode=verify-fullPartes:
postgresql://: esquema del URI.app_user: rol utilizado para autenticarse.password: secreto; debe codificarse si contiene caracteres reservados.host: DNS, IP o ruta de socket según cliente.5432: puerto.domisys: database seleccionada.sslmode: política TLS del cliente libpq.Una URL es cómoda, pero puede filtrarse en logs, traces, mensajes de error o historial. En producción usa gestores de secretos y evita registrar la URL completa.
psql "postgresql://app_user@localhost:5432/domisys"psql utiliza libpq y puede obtener parámetros de flags, variables de entorno, service files y archivos de contraseña.
Metacommands útiles:
\conninfo muestra la conexión actual
\l lista databases
\c database cambia de database abriendo otra conexión
\dn lista schemas
\dt app.* lista tablas del schema app
\d+ app.orders describe tabla, índices y almacenamiento
\du lista roles
\x auto alterna salida expandida
\timing on mide tiempo del lado cliente
\pset pager off desactiva pager
\i migration.sql ejecuta un archivo
\watch 2 repite una consulta cada 2 segundos
\q cierra psqlEstos comandos comienzan con \ porque los interpreta psql; no se envían como SQL al servidor.
export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=domisys
export PGUSER=app_user
export PGSSLMODE=prefer
psqlPermiten separar parámetros sin escribir una URI. PGPASSWORD existe, pero puede exponerse a herramientas del sistema o scripts. Para desarrollo local, .pgpass puede ser más seguro si sus permisos son restrictivos.
Formato conceptual de .pgpass:
hostname:port:database:username:passwordEn Unix, libpq exige permisos equivalentes a 0600; de lo contrario puede ignorarlo.
No intenta TLS. Solo es razonable en un canal local o red completamente controlada cuando el riesgo está entendido.
Intenta TLS y puede degradar a texto plano. Es práctico localmente, pero no establece una garantía fuerte.
Exige cifrado, aunque su comportamiento de verificación depende de archivos de certificados disponibles y versión del cliente. No debe confundirse con identidad completa.
Valida que el certificado provenga de una CA confiable.
Además valida que el hostname coincida. Es la opción más fuerte para conexiones TCP de producción.
TLS protege el canal, no corrige roles con permisos excesivos ni credenciales filtradas.
pg_hba.conf define qué conexiones se permiten y cómo se autentican:
hostssl domisys app_user 10.20.0.0/16 scram-sha-256La regla expresa:
domisys.app_user.El orden importa: PostgreSQL utiliza la primera regla coincidente. Editar el archivo requiere reload, no necesariamente restart.
La aplicación no debería conectarse como superuser ni como owner de todas las tablas.
Separación típica:
migration_role
→ crea y altera objetos
app_role
→ SELECT/INSERT/UPDATE/DELETE necesarios
readonly_role
→ consultas y reportingEl owner puede alterar o eliminar objetos, incluso cuando no se le otorgaron privilegios explícitos. Separar ownership reduce el impacto de una inyección SQL o credencial comprometida.
getent hosts db.example.internalO una herramienta equivalente. Confirma que el hostname apunta al destino esperado.
nc -vz db.example.internal 5432Un puerto abierto no garantiza autenticación, pero confirma red básica.
psql -h host -p 5432 -U app_user -d domisysDistingue red, TLS, rol, password, HBA y database.
Desde una sesión administrativa:
SELECT version();
SHOW server_version;
SHOW data_directory;
SHOW hba_file;
SHOW config_file;SELECT pid, usename, datname, client_addr, state, wait_event_type, wait_event
FROM pg_stat_activity
WHERE datname = current_database();Una aplicación web no debe abrir una conexión física nueva para cada consulta ni mantener conexiones ilimitadas.
Modelo esperado:
requests concurrentes
↓
pool de aplicación
↓ número limitado de conexiones
PostgreSQLEl pool amortiza autenticación y creación de procesos. Sin embargo, un pool demasiado grande puede saturar PostgreSQL. El tamaño debe considerar todas las réplicas de la aplicación, jobs y herramientas administrativas.
Datos reproducibles, credenciales sin privilegios de producción y posibilidad de reinicio.
Instancia o database aislada, migraciones automáticas y limpieza determinista. No compartas estado entre suites concurrentes sin estrategia.
Debe parecerse a producción en versiones, extensiones, TLS y configuración relevante, sin copiar secretos ni datos sensibles completos.
Requiere backups verificados, monitoreo, acceso privado, TLS, roles mínimos, gestión de cambios y respuesta a incidentes.
El protocolo conserva amplia compatibilidad, pero herramientas administrativas deben alinearse con la major version cuando sea importante.
Ejemplos:
pg_dump debería ser de la misma major o más reciente que el servidor fuente dentro de sus reglas de compatibilidad.psql pueden depender de catálogos nuevos.Otra instancia o proceso puede usar 5432. Cambia puerto conscientemente y revisa qué cliente está alcanzando.
psql sin -h suele usar socket local en Unix. -h localhost fuerza TCP y puede activar reglas HBA distintas.
La credencial pertenece a un rol; no existe un “usuario de database” separado del rol PostgreSQL.
Cuando omites -d, algunos clientes intentan conectarse a una database con el nombre del rol. Puede producir database does not exist aunque el rol sea válido.
PgBouncer cambia semántica de sesión según modo. Temporary tables, prepared statements y parámetros de sesión pueden comportarse distinto en transaction pooling.
Parece evitar problemas de permisos, pero convierte cualquier fallo en acceso casi total. Crea un rol mínimo.
Facilita fuerza bruta y amplía superficie. Usa red privada, firewall, VPN o proxy administrado.
Filtra credenciales y dificulta rotación. Usa secretos externos y configuración validada.
Puede ser DNS, firewall, agotamiento de pool o red. Diagnostica por capas.
Los datos desaparecen al reemplazar el contenedor. Un volumen conserva datos, pero aún requiere backup.
psql es cliente; sus metacommands no son SQL.verify-full ofrece la validación TLS más fuerte en libpq.pg_hba.conf decide el método de acceso según la primera regla coincidente.connection refused y password authentication failed requieren investigaciones diferentes?sslmode=verify-full y qué no protege?Modelo relacional: información, relaciones y claves explica cómo transformar un dominio en relaciones con identidad e integridad antes de escribir SQL.