Connection String Builder

Anatomía de una URI de conexión estándar

La mayoría de drivers modernos aceptan el formato URI definido de forma implícita por libpq y adoptado después por MongoDB y Redis: esquema://usuario:contraseña@host:puerto/basedatos?parametro=valor. Por ejemplo, postgresql://app_user:S3cr3t@10.0.4.12:5432/facturacion?sslmode=require conecta al usuario app_user contra la base facturacion en el host 10.0.4.12, exigiendo TLS. El esquema determina el driver: postgresql:// o postgres:// para PostgreSQL, mysql:// para MySQL/MariaDB, mongodb:// para MongoDB, redis:// o rediss:// (con TLS) para Redis. Si algún componente falta, el driver aplica su valor por defecto: puerto 5432 en PostgreSQL, 3306 en MySQL, 27017 en MongoDB, 6379 en Redis.

Escapado de caracteres especiales en usuario y contraseña

Si la contraseña contiene @, :, /, ? o #, esos caracteres colisionan con la sintaxis de la URI y el parseo falla de forma silenciosa o parcial. Una contraseña P@ss:2024/x debe codificarse en percent-encoding como P%40ss%3A2024%2Fx antes de insertarla en la cadena. Este es el motivo más común por el que una conexión funciona en un script de pruebas con contraseña simple y falla en producción con la contraseña real generada por un gestor de secretos. El constructor aplica automáticamente encodeURIComponent a usuario y contraseña, evitando este fallo típico que suele diagnosticarse mal como un problema de red o de firewall.

sslmode en PostgreSQL: disable, require, verify-ca, verify-full

PostgreSQL soporta seis niveles de sslmode. disable no usa TLS en ningún caso; allow y prefer negocian pero no lo exigen; require obliga a cifrar pero no valida el certificado del servidor, dejando la puerta abierta a un ataque man-in-the-middle; verify-ca valida que el certificado esté firmado por una CA de confianza; verify-full además comprueba que el hostname coincide con el del certificado. Para conexiones desde una aplicación a una base gestionada como RDS o Cloud SQL, el mínimo razonable en producción es verify-full con el certificado raíz del proveedor cargado en sslrootcert. Usar solo require en un entorno regulado es un hallazgo habitual en auditorías de seguridad.

Parámetros de pool y timeouts que cambian el comportamiento real

Más allá del host y el puerto, los parámetros de query string controlan el rendimiento bajo carga. En Node con pg, connect_timeout=10 evita que una conexión colgada bloquee el arranque del proceso; en Prisma, connection_limit=10 limita cuántas conexiones simultáneas abre el pool hacia PostgreSQL, algo crítico cuando la base tiene max_connections=100 y conviven varias réplicas del servicio. En MySQL, useSSL=false&allowPublicKeyRetrieval=true es habitual en entornos de desarrollo local con el driver Connector/J, pero nunca debería llegar a producción. Ignorar estos parámetros produce errores intermitentes bajo carga que son difíciles de reproducir en local porque solo aparecen con concurrencia real.

Cadenas de conexión para MongoDB Atlas y réplicas

MongoDB introduce el esquema mongodb+srv:// para resolver automáticamente, vía un registro DNS SRV, la lista de nodos de un replica set o clúster de Atlas, sin necesidad de listar cada host y puerto manualmente. Una cadena típica es mongodb+srv://usuario:pass@cluster0.abcde.mongodb.net/produccion?retryWrites=true&w=majority. El parámetro w=majority exige que la escritura se confirme en la mayoría de nodos antes de devolver éxito al cliente, lo que prioriza consistencia sobre latencia; en operaciones donde una pérdida ocasional es aceptable, w=1 reduce el tiempo de respuesta a costa de esa garantía.

Diferencias entre variables de entorno y cadenas embebidas

Guardar la cadena completa en una única variable DATABASE_URL simplifica la configuración en frameworks como Rails, Prisma o Django, pero mezcla credenciales y configuración de red en un solo secreto que hay que rotar entero. La alternativa es exponer variables separadas (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME) y construir la cadena en tiempo de arranque, lo que facilita rotar solo la contraseña sin tocar el resto. En Kubernetes esto se traduce en inyectar la contraseña desde un Secret y el resto desde un ConfigMap, evitando que el host de la base de datos quede versionado junto al secreto en un mismo objeto.

Verificar la conexión antes de desplegar

Antes de confiar una cadena a un pipeline de despliegue, verifícala con el cliente nativo: psql "postgresql://app_user:pass@10.0.4.12:5432/facturacion?sslmode=require" para PostgreSQL, o mysql --host=10.0.4.12 --port=3306 -u app_user -p facturacion para MySQL. Si el cliente conecta pero la aplicación no, el problema suele estar en el parseo de caracteres especiales por parte del driver de la aplicación, no en la red. Comprobar primero con la herramienta de línea de comandos aísla en segundos si el fallo es de conectividad (firewall, security group) o de la propia cadena.

Salidas reales de ejemplo

$ psql "postgresql://app_user:S3cr3t@10.0.4.12:5432/facturacion?sslmode=require"
Password for user app_user: 
psql (16.2)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

facturacion=> \conninfo
You are connected to database "facturacion" as user "app_user" on host "10.0.4.12" at port "5432".
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)

$ node -e "new (require('pg').Pool)({connectionString:'postgresql://app_user:P@ss2024@10.0.4.12:5432/facturacion'})"
node:internal/errors: getaddrinfo ENOTFOUND ss2024
    at GetAddrInfoReqWrap.onlookup [as oncomplete]
Error: getaddrinfo ENOTFOUND ss2024

$ mongosh "mongodb+srv://usuario:pass@cluster0.abcde.mongodb.net/produccion?retryWrites=true&w=majority"
Connecting to: mongodb+srv://<credentials>@cluster0.abcde.mongodb.net/produccion
Using MongoDB: 7.0.5
Atlas atlas-3f9k2p-shard-0 [primary] produccion> 

jdbc:mysql://10.0.6.20:3306/inventario?useSSL=true&serverTimezone=UTC&connectTimeout=5000&maxPoolSize=15

Casos de uso comunes

• Migrar credenciales de un servicio a variables de entorno sin romper el parseo del driver.
• Generar la DATABASE_URL correcta para Prisma, TypeORM o Sequelize a partir de campos separados.
• Diagnosticar por qué una app falla al conectar con una contraseña que contiene símbolos.
• Configurar sslmode correctamente al migrar de una base local a un proveedor gestionado como RDS.
• Construir cadenas mongodb+srv para clústeres de MongoDB Atlas sin listar cada nodo a mano.

Buenas prácticas

• Aplica siempre percent-encoding a usuario y contraseña antes de insertarlos en la URI.
• Usa verify-full en producción cuando el proveedor exponga un certificado raíz descargable.
• Separa host y credenciales en Secrets distintos de ConfigMaps en Kubernetes.
• Fija connect_timeout y connection_limit explícitos; no confíes en los valores por defecto del driver.
• Verifica la cadena con el cliente nativo (psql, mysql, mongosh) antes de desplegarla en la aplicación.

Referencias oficiales

• PostgreSQL – Connection Strings
• MongoDB – Connection String URI Format
• MySQL – Connector/J Connection URL Syntax