// herramienta gratuita

Constructor de cadenas de conexión de PostgreSQL

Crea un URI de conexión de PostgreSQL, una cadena de palabras clave/valor de libpq, una cadena de Npgsql (ADO.NET), una URL JDBC y más a partir de un solo formulario, o pega cualquiera de ellos para ver qué hace cada parámetro y si sslmode realmente te protege. Todo se ejecuta en tu navegador: nada de lo que escribas se envía a ningún lugar.

Abrir esta conexión en SQLly

Abre el editor de conexiones de SQLly con los datos ya rellenados.

Privado por diseño. El constructor y el decodificador son JavaScript puro que se ejecuta en esta pestaña. La página no envía ninguna solicitud con lo que escribes, no almacena nada (ni siquiera en tu navegador) y sigue funcionando sin conexión una vez cargada. El enlace Abrir en SQLly va directamente desde tu navegador a la aplicación en tu computadora.

Formatos de cadena de conexión de PostgreSQL

La mayoría de los controladores de PostgreSQL se basan en libpq o copian sus reglas, por lo que el URI postgresql://user:password@host:5432/db?sslmode=verify-full y la forma de palabra clave/valor host=... dbname=... funcionan casi en todas partes: psql, psycopg, pgx, lib/pq, node-postgres. Npgsql (.NET) y pgJDBC (Java) tienen sus propias formas de escribir.

El parámetro que más importa es sslmode. Su valor predeterminado, prefer, usa TLS cuando el servidor lo ofrece, pero nunca comprueba el certificado y pasa silenciosamente a texto sin cifrar. Solo verify-full verifica tanto la cadena de certificados como el nombre del host.

URI libpq, psql, psycopg, pgx, node-postgres, Prisma

postgresql://app_user:[email protected]/sales?sslmode=verify-full

Palabra clave/valor libpq conninfo, psycopg, pgx, lib/pq

host=db.example.com dbname=sales user=app_user password=your_password sslmode=verify-full

ADO.NET (Npgsql) Npgsql, Entity Framework Core

Host=db.example.com;Database=sales;Username=app_user;Password=your_password;SSL Mode=VerifyFull

JDBC Controlador JDBC de PostgreSQL (pgJDBC)

jdbc:postgresql://db.example.com/sales?user=app_user&password=your_password&sslmode=verify-full

ODBC psqlODBC

Driver={PostgreSQL Unicode};Server=db.example.com;Database=sales;Uid=app_user;Pwd=your_password;SSLmode=verify-full;

URL de SQLAlchemy Python SQLAlchemy con psycopg 3

postgresql+psycopg://app_user:[email protected]/sales?sslmode=verify-full

Varios hosts (conmutación por error) libpq 10+, pgx, Npgsql, pgJDBC

postgresql://[email protected]:5432,db2.example.com:5432/sales?target_session_attrs=read-write

Los marcadores de posición como your_password son eso mismo: construye tu propia cadena con el formulario de arriba. Más sobre cómo conectar SQLly a PostgreSQL: SQLly para PostgreSQL.

parámetros de libpq (URI y palabra clave/valor)

Formato URI: postgresql://[user[:password]@][host][:port][,...][/dbname][?param=value&...] (postgres:// también funciona); aplica la codificación porcentual a los caracteres especiales, incluidas las barras de una ruta de socket de Unix usada como host. Formato palabra clave/valor: key=value pares separados por espacios; pon comillas simples a un valor que esté vacío o contenga espacios, y escribe \' y \\ para una comilla o barra invertida dentro de él.

Palabra claveSinónimosPredeterminadoLo que hace
host - Socket Unix en /tmp (localhost en Windows) Nombre del host, IP o un directorio para un socket Unix. Se prueba una lista separada por comas en orden.
hostaddr - - IP numérica, omitiendo DNS (el host todavía se usa para las verificaciones TLS).
port - 5432 (el valor predeterminado de la compilación) Un puerto, o uno por host.
dbname - el nombre de usuario Base de datos a la que conectarse.
user - el usuario del sistema operativo Rol con el que conectarse.
password - - Mejor mantenerlo en ~/.pgpass (o PGPASSWORD) que en la cadena.
passfile - ~/.pgpass (%APPDATA%\postgresql\pgpass.conf en Windows) Archivo de contraseñas.
connect_timeout - 0 (esperar indefinidamente) Segundos por host. PostgreSQL 16 y versiones anteriores tratan 1 como 2.
sslmode - prefer disable, allow, prefer, require, verify-ca, verify-full. require verifica la CA solo si existe un archivo de certificado raíz; solo verify-full verifica el nombre del host.
sslrootcert - ~/.postgresql/root.crt Archivo CA. system (16+) usa las CAs de confianza del sistema operativo y establece verify-full esto como predeterminado.
sslcert / sslkey - ~/.postgresql/postgresql.crt / .key Certificado y clave del cliente.
sslnegotiation - postgres 17+. direct inicia TLS de inmediato (requiere sslmode require o superior).
application_name - - Mostrado en pg_stat_activity y en el registro del servidor.
options - - Ajustes del servidor al inicio, por ejemplo -c statement_timeout=30000 -c search_path=app.
target_session_attrs - cualquiera any, read-write, read-only, primary, standby, prefer-standby.
load_balance_hosts - deshabilitar 16+. random mezcla la lista de hosts.
keepalives - 1 keepalives TCP activados/desactivados; ajustar con keepalives_idle, keepalives_interval, keepalives_count.
channel_binding - prefer require se niega a autenticarse sin la vinculación de canal SCRAM.

Parámetros Npgsql (ADO.NET)

Npgsql usa ADO.NET Key=Value; sintaxis con sus propios nombres de palabras clave. Entrecomilla los valores que contengan ; con comillas dobles.

Palabra claveSinónimosPredeterminadoLo que hace
Host Servidor - (obligatorio) Nombre de host, IP, una lista separada por comas o un directorio de sockets que comience con /.
Port - 5432 Puerto TCP.
Database DB el nombre de usuario Nombre de la base de datos.
Username Nombre de usuario, Id de usuario, UID PGUSER; si no, el usuario del SO Nombre del rol.
Password PSW, PWD PGPASSWORD Contraseña.
SSL Mode SslMode Preferir Disable, Allow, Prefer, Require, VerifyCA, VerifyFull. Desde Npgsql 6, Require no valida el certificado.
Trust Server Certificate - falso Omitir la validación. Npgsql 6 y 7 lo requerían con Require; Npgsql 8 no lo hace.
Root Certificate - PGSSLROOTCERT Archivo CA para VerifyCA / VerifyFull.
Timeout - 15 Segundos de espera por una conexión.
Command Timeout - 30 Tiempo de espera predeterminado para comandos en segundos; 0 espera indefinidamente.
Application Name - PGAPPNAME application_name.
Search Path - - Ruta de búsqueda de esquemas.
Target Session Attributes - cualquiera any, primary, standby, prefer-primary, prefer-standby, read-write, read-only.
Pooling - verdadero Agrupación de conexiones.
Maximum Pool Size - 100 Pool más grande.
Minimum Pool Size - 0 Pool más pequeño.
Keepalive - 0 (desactivado) Segundos entre consultas de mantenimiento de conexión.
Include Error Detail - falso Incluye el detalle de los errores del servidor, que puede contener datos de filas, en los mensajes de excepción.

Propiedades de pgJDBC

Formato de URL: jdbc:postgresql://host:port/database?property=value&.... pgJDBC no lee user:password@ en la URL: pasa user y password como parámetros o propiedades de conexión.

Palabra claveSinónimosPredeterminadoLo que hace
user / password - - Credenciales.
sslmode - prefer Mismos valores que libpq. require, allow y prefer no valida el certificado.
ssl - falso true sin sslmode significa verify-full.
sslrootcert - ~/.postgresql/root.crt Archivo CA.
connectTimeout - 10 Segundos de espera por el socket; 0 desactiva el límite.
socketTimeout - 0 Segundos que puede bloquearse una lectura; 0 espera indefinidamente.
loginTimeout - 0 Segundos de espera por todo el inicio de sesión.
ApplicationName - Controlador JDBC de PostgreSQL application_name.
currentSchema - - search_path, separado por comas.
targetServerType - cualquiera any, primary, secondary, preferPrimary, preferSecondary.
options - - Opciones de inicio, por ejemplo -c statement_timeout=30000 (codificado en porcentaje en la URL).

Errores comunes de conexión a PostgreSQL

FATAL: no pg_hba.conf entry for host "10.0.0.7", user "app_user", database "sales", no encryption

Por qué: Se contactó al servidor, pero ninguna línea en pg_hba.conf permite este cliente, usuario y base de datos, o la línea que coincide es hostssl y te conectaste sin TLS («sin cifrado»).

Solución: Conéctate con sslmode=require o más fuerte si el servidor espera TLS, o pide al administrador que añada una host/hostssl línea para tu dirección y recarga el servidor.

connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused

Por qué: Nada está escuchando en esa dirección y puerto: el servidor está caído, listen_addresses solo cubre localhost, el puerto es diferente, o un firewall rechaza la conexión.

Solución: Comprobar listen_addresses y port en postgresql.conf, el firewall o el grupo de seguridad en la nube, y si necesitas un puerto distinto (los servicios gestionados y los poolers suelen usar 6432 o uno personalizado).

FATAL: password authentication failed for user "app_user"

Por qué: Contraseña incorrecta, un rol sin contraseña, o un carácter especial de la contraseña que no estaba codificado en porcentaje en el URI, así que el controlador leyó otra contraseña.

Solución: Verifica la contraseña; en un URI codifica @ como %40, : como %3A, / como %2F y % como %25. Pega el URI en el decodificador para ver exactamente qué contraseña enviará el driver.

server does not support SSL, but SSL was required

Por qué: La cadena solicita sslmode=require (o verify-ca / verify-full) y el servidor tiene ssl = off.

Solución: Activa TLS en el servidor o conéctate al endpoint TLS que documente tu proveedor. No bajes a sslmode=disable a través de una red que no controles.

root certificate file "/home/app/.postgresql/root.crt" does not exist

Por qué: sslmode=verify-ca o verify-full necesita un certificado CA contra el que verificar, y libpq no encontró ninguno en la ruta predeterminada.

Solución: Descarga el paquete de CA de tu proveedor y configura sslrootcert=/path/to/ca.pem, o en clientes PostgreSQL 16+ usa sslrootcert=system cuando el certificado del servidor provenga de una CA pública.

FATAL: database "app_user" does not exist

Por qué: No dbname se proporcionó, así que libpq usó el nombre de usuario como nombre de la base de datos.

Solución: Añade la base de datos a la ruta URI (/sales) o configura dbname=sales.

invalid connection option "sslmod"

Por qué: libpq rechaza toda la cadena cuando una palabra clave está mal escrita o pertenece a otro controlador (por ejemplo ApplicationName de pgJDBC en lugar de application_name).

Solución: Corrige la ortografía. El decodificador enumera todos los parámetros de libpq y marca los desconocidos.

Preguntas frecuentes sobre la cadena de conexión de PostgreSQL

¿Cuál es el formato de la cadena de conexión de PostgreSQL?

Dos formas funcionan con controladores basados en libpq: el URI postgresql://user:password@host:5432/dbname?sslmode=verify-full y la cadena de palabra clave/valor host=host port=5432 dbname=dbname user=user sslmode=verify-full. Npgsql usa Host=...;Database=...;Username=... y Java usa jdbc:postgresql://host:5432/dbname.

¿Qué sslmode debería usar?

verify-full con sslrootcert apuntando a tu CA (o system en PostgreSQL 16+). require cifra pero no verifica quién respondió, y prefer, el valor predeterminado, puede pasar silenciosamente a texto sin cifrar. Usa disable solo para un socket o localhost.

¿Cómo escapo caracteres especiales en un URI de PostgreSQL?

Codifícalos con porcentaje en el nombre de usuario, la contraseña y la base de datos: @ es %40, : es %3A, / es %2F, # es %23, ? es %3F, % es %25 y un espacio es %20. La forma clave/valor evita la mayor parte de esto: envuelve el valor entre comillas simples y escapa ' y \ con una barra invertida.

¿Cómo defino un tiempo de espera de instrucción en la cadena de conexión?

Con controladores basados en libpq, añade options=-c statement_timeout=30000 (milisegundos; codifícalo como porcentaje en un URI como options=-c%20statement_timeout%3D30000). Npgsql tiene Command Timeout, un tiempo de espera del cliente, en segundos.

¿Puedo listar varios hosts para conmutación por error?

Sí. Escribe postgresql://host1:5432,host2:5432/db o host=host1,host2 port=5432,5432. libpq los prueba en orden; añade target_session_attrs=read-write para omitir los standbys de solo lectura, o load_balance_hosts=random (PostgreSQL 16+) para repartir las conexiones.

¿Por qué node-postgres verifica el certificado con sslmode=require?

pg-connection-string actualmente trata sslmode=prefer, require y verify-ca como verify-full y muestra una advertencia de que esto cambiará a los significados de libpq en una futura versión principal. Añade uselibpqcompat=true para optar por el comportamiento de libpq ahora, o configura ssl mejor en la configuración del cliente.

// olvídate de las cadenas por completo

Conéctate una vez. Luego solo escribe SQL.

SQLly es un entorno de trabajo SQL nativo para macOS, Windows y Linux. Pega una cadena de conexión en su editor de conexiones, guarda las contraseñas en el llavero del sistema y obtén IntelliSense que entiende el esquema en PostgreSQL, entre otros.