Iniciar sesión y autenticarse en PostgreSQL

Usa psql para conectarte a una base de datos PostgreSQL concreta y especifica el host, el puerto, la base de datos y el rol cuando sea necesario. Una conexión local puede usar la identidad predeterminada del sistema operativo; una conexión remota o autenticada con contraseña suele requerir parámetros explícitos y reglas de autenticación del servidor compatibles.

Conectarse a PostgreSQL con psql

Usa -h para indicar el host del servidor, -p para el puerto, -U para el rol y -d para la base de datos. Por ejemplo, puedes solicitar una conexión TCP con psql -h localhost -p 5432 -U app_user -d products_db. El puerto predeterminado suele ser 5432, aunque el servidor puede estar configurado para escuchar en otro.

Si omites -U, normalmente psql usa el nombre de la cuenta del sistema operativo; si omites -d, normalmente usa ese nombre de rol como nombre de la base de datos. Variables de entorno como PGUSER, PGDATABASE y PGHOST, o una definición de servicio, pueden proporcionar parámetros de conexión y cambiar lo que usa un comando psql sin opciones. No es imprescindible que exista una base de datos con el mismo nombre si seleccionas explícitamente otra base de datos existente.

Una conexión local mediante socket de dominio Unix y una conexión TCP pueden coincidir con reglas distintas de pg_hba.conf: las reglas local se aplican a las conexiones por socket y las reglas host, a las conexiones TCP. Por eso, el mismo rol y la misma contraseña pueden comportarse de manera diferente según si el cliente se conecta mediante un socket o especifica un host. Si la autenticación no funciona como esperas, comprueba las reglas del servidor y el método de conexión elegido.

En el código de una aplicación, crea los argumentos de forma explícita para que cada valor se mantenga como un argumento independiente. Este ejemplo de Python prepara una solicitud TCP; no se conecta a un servidor PostgreSQL.

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

arguments = [
    "psql",
    "-h", "localhost",
    "-p", "5432",
    "-U", "app_user",
    "-d", "products_db",
]
assert arguments[0] == "psql"
assert arguments[-1] == "products_db"

Crear un rol y una base de datos coincidentes con createuser y createdb

En una instalación local de PostgreSQL, un administrador puede crear un rol de inicio de sesión y una base de datos para la cuenta actual del sistema operativo. En los sistemas donde la cuenta de administrador de PostgreSQL se llama postgres, ejecuta sudo -u postgres createuser "$USER" para crear el rol y, después, ejecuta createdb con esa cuenta del sistema operativo para crear una base de datos con el mismo nombre. Estos comandos requieren los permisos locales adecuados y que haya un servidor disponible. No es necesario convertir el rol de la aplicación en superusuario.

Si quieres una base de datos con otro nombre, un administrador puede ejecutar createdb -O app_user products_db para crearla y asignarle la propiedad a app_user. Luego, conéctate con psql -d products_db -U app_user. El rol debe existir y el cliente debe llegar a la instancia del servidor donde se crearon ese rol y esa base de datos. Las utilidades de línea de comandos también pueden usar variables de entorno de PostgreSQL; por tanto, especifica las opciones de conexión si se puede seleccionar entre varios servidores locales o remotos.

Crear un rol de inicio de sesión y una base de datos con SQL

Como alternativa, conéctate a una base de datos administrativa con un rol autorizado a crear roles y bases de datos; luego ejecuta CREATE ROLE app_user LOGIN; y CREATE DATABASE products_db OWNER app_user;. LOGIN permite que el rol inicie una sesión; ser propietario le da control sobre la base de datos nueva, pero no lo convierte en superusuario. Para usar autenticación con contraseña, establece un secreto mediante un proceso seguro de aprovisionamiento o usa \password app_user en psql, de modo que la contraseña no quede en el historial SQL. Evita incluir credenciales reales en scripts o ejemplos.

Para solicitar una conexión TCP autenticada con contraseña, ejecuta psql -h localhost -p 5432 -U app_user -d products_db. psql solicita la contraseña cuando hace falta. La contraseña por sí sola no garantiza que se use autenticación con contraseña: la regla correspondiente de pg_hba.conf debe permitir la conexión y utilizar un método de contraseña adecuado, y el servidor debe estar configurado para aceptar conexiones TCP. Si el host o el puerto difieren de estos ejemplos para desarrollo local, usa los valores reales del servidor.

Verificar la autenticación y solucionar errores de conexión frecuentes

Después de conectarte, comprueba que el indicador de comandos muestre la base de datos y el rol previstos. En el indicador de psql, \conninfo muestra los detalles de la conexión, y SELECT current_user, current_database(); confirma el rol y la base de datos activos. Estas comprobaciones ayudan a detectar una conexión correcta que, sin embargo, apunta al destino equivocado.

Un mensaje como FATAL: role "david" does not exist significa que el servidor al que llegaste no tiene un rol llamado david; si ejecutaste psql sin opciones, ese nombre puede proceder de la cuenta del sistema operativo o de un parámetro de conexión que la haya reemplazado. Comprueba primero el host, el puerto y PGUSER; después, confirma que el rol exista en ese servidor. Si el rol existe pero falla la conexión a la base de datos, comprueba PGDATABASE o -d y confirma que la base de datos exista. Si falla la contraseña, verifica la contraseña y la regla aplicable de pg_hba.conf; si se rechaza la conexión, confirma que el servidor esté en ejecución, escuche en la dirección y el puerto elegidos, y sea accesible desde el cliente. Los indicadores de comandos y los mensajes de diagnóstico de PostgreSQL varían según la versión y la configuración; considera los ejemplos representativos, no una salida fija.