Capítulo 2: Conexiones y Túneles

Información: Este capítulo cubre el establecimiento de conexiones directas a bases de datos, la configuración de túneles SSH Jump Host y HTTP PHP, las etiquetas de color de entorno y el almacenamiento seguro de credenciales.

En este capítulo:

• 2.1 Establecer una conexión directa
• 2.2 Perfiles de conexión y entornos seguros
• 2.3 Túnel SSH Jump Host
• 2.4 Túnel HTTP PHP (sqloz-tunnel.php)
• 2.5 Etiquetas de color de entorno
• 2.6 Almacenamiento seguro de credenciales
• Temas relacionados

2.1 Establecer una conexión directa

Siga estos pasos para conectarse a una base de datos alojada en una máquina local o en un servidor expuesto a Internet.

1. Presione Cmd + N o use el menú Archivo → Nueva conexión….
2. En la pestaña General, complete los siguientes campos:
   • Nombre de conexión: Un nombre descriptivo (ej. Producción E-Commerce Principal).
   • Motor: Seleccione MySQL, PostgreSQL o SQLite local. MariaDB utiliza la familia de perfiles MySQL y se detecta tras la conexión; no se muestra como un elemento separado. MySQL 8.0/8.4, MariaDB 10.6/11.4 y PostgreSQL 16 componen la matriz de pruebas actual, no requisitos mínimos. Consulte el Capítulo 22.
   • Host y Puerto: La dirección del servidor y el puerto (MySQL por defecto 3306, PostgreSQL 5432).
   • Usuario y Contraseña: El usuario y la contraseña.
3. Verifique la conexión con Probar conexión. Una vez confirmada con éxito, conéctese con Guardar y conectar.

2.2 Perfiles de conexión y entornos seguros

Los perfiles de conexión guardados almacenan configuraciones no confidenciales como el nombre, motor, host, puerto, base de datos, color del entorno y preferencia de solo lectura. Las contraseñas y claves de túnel se almacenan en el Llavero de macOS (Keychain).

• Use Guardar y conectar para crear un perfil reutilizable.
• Utilice la opción de conexión solo para esta sesión si requiere un acceso temporal que no deba quedar registrado.
• Asigne colores Prod, Staging, Dev, Test o Sandbox para que el espacio de trabajo activo y el explorador de objetos indiquen con claridad el entorno en uso.
• Active la opción Solo lectura del perfil antes de inspeccionar una base de producción. El editor y la cuadrícula rechazarán automáticamente cualquier operación de modificación de datos.

2.3 Túnel SSH Jump Host

En numerosos entornos corporativos, el servidor de base de datos no está expuesto directamente a redes externas; se accede exclusivamente mediante un servidor de salto o bastión (Jump Host). SQLOZ incluye un túnel SSH nativo para este escenario.

[SQLOZ] --(Túnel SSH / Puerto 22)--> [SSH Jump Host] --(Red local)--> [Servidor de Base de Datos]

Pasos de configuración:

1. En el cuadro de diálogo de conexión, pase a la pestaña Túnel SSH.
2. Marque Habilitar túnel SSH.
3. Ingrese la dirección del servidor SSH (Host SSH), el puerto (22 por defecto) y el nombre de usuario.
4. Elija una de las siguientes opciones de Método de autenticación:
   • Clave privada (recomendado): Seleccione el archivo ~/.ssh/id_ed25519 o id_rsa; introduzca la frase de contraseña si corresponde.
   • Contraseña: La contraseña SSH.
5. Verifique el túnel con Probar conexión. SQLOZ abrirá el túnel en segundo plano e iniciará la sesión de base de datos.

Consejo: La autenticación por clave privada es preferible a la contraseña por ofrecer mayor seguridad y facilitar la automatización.

2.4 Túnel HTTP PHP (sqloz-tunnel.php)

En alojamientos compartidos (cPanel/DirectAdmin), el puerto 3306 suele estar bloqueado al exterior y no se proporciona acceso SSH. En tal caso, la base de datos solo es accesible mediante PHP en el servidor web. SQLOZ proporciona un túnel HTTP que utiliza el script sqloz-tunnel.php.

[SQLOZ] --(HTTPS POST / Token Cifrado)--> [sqloz-tunnel.php] --(localhost:3306)--> [Servidor MySQL]

Pasos de instalación:

1. Suba el archivo sqloz-tunnel.php incluido en el paquete de instalación de SQLOZ a la carpeta web del alojamiento (ej. public_html/).
2. Modifique la línea $TOKEN = "su_clave_secreta"; en el script con una clave robusta. El script rechazará su ejecución con un error HTTP 500 hasta que se modifique el token por defecto.
3. En la configuración de SQLOZ, marque la pestaña Túnel HTTP:
   • URL del túnel: https://example.com/sqloz-tunnel.php
   • Secreto compartido (Shared Secret): El token secreto configurado en el script.
4. Verifique el túnel con Probar conexión.

Envío de credenciales de base de datos

Importante: El usuario y la contraseña de la base de datos jamás se escriben en el archivo sqloz-tunnel.php. En el script solo se define el SQTUNNEL_TOKEN (secreto compartido).

El script PHP no ejecuta ningún controlador de base de datos ni lee la contraseña en texto claro. Su cometido consiste únicamente en transmitir bytes binarios puros (proxy TCP de bytes sin procesar):

1. El controlador local de SQLOZ lee el paquete de bienvenida (Server Greeting) emitido por el servidor a través del túnel.
2. El controlador cifra el usuario y la contraseña introducidos según el protocolo binario estándar del motor (Client Authentication Packet).
3. El paquete binario se codifica en base64 y se envía al script a través de una conexión HTTPS cifrada.
4. El script decodifica el paquete e inyecta los bytes directamente en el socket TCP de la base de datos. El servidor autentica la identidad y se establece la sesión.

Variables de entorno de configuración

El script sqloz-tunnel.php puede configurarse dentro del propio archivo PHP o mediante variables de entorno en el servidor web.

Variable de entorno	Descripción	Por defecto
SQTUNNEL_HOST	Dirección del servidor MySQL de destino	127.0.0.1
SQTUNNEL_PORT	Puerto del servidor MySQL de destino	3306
SQTUNNEL_TOKEN	Clave de acceso secreta requerida al cliente	Obligatorio
SQTUNNEL_MAX_SESSIONS	Máximo de sesiones activas simultáneas	16
SQTUNNEL_IDLE_TIMEOUT	Tiempo de finalización para procesos inactivos (seg)	3600
SQTUNNEL_LOCKOUT_THRESHOLD	Umbral de bloqueo de IP por fallos (protección contra fuerza bruta)	5
SQTUNNEL_LOCKOUT_WINDOW	Ventana de bloqueo por fuerza bruta (seg)	60

2.5 Etiquetas de color de entorno

Al gestionar múltiples pestañas abiertas simultáneamente, existe un alto riesgo de ejecutar consultas en el entorno equivocado (ej. producción). SQLOZ mitiga este peligro mediante etiquetas visuales de color.

Asigne un color a cada entorno en la pestaña General:

• Prod (Rojo - #E8334A): Servidores de producción en vivo.
• Staging (Naranja - #FF9500): Entornos de pruebas y preproducción.
• Dev (Verde - #34C759): Entorno de desarrollo local.
• Test (Azul - #007AFF) y Sandbox (Púrpura - #AF52DE): Entornos de pruebas aislados.
• Color personalizado: Defina un tono a medida mediante el selector de Apple o un código hexadecimal.

2.6 Almacenamiento seguro de credenciales

SQLOZ no almacena contraseñas de bases de datos ni de túneles SSH en archivos de texto, configuraciones ni registros. Todas las credenciales sensibles se transfieren al almacén con cifrado por hardware Llavero de macOS (Keychain).

Consejo: Guardar contraseñas únicamente en el Llavero de macOS evita que las credenciales sean interceptadas por otro software o dispositivos.

Temas relacionados

• Capítulo 1: Primeros pasos
• Capítulo 10: Seguridad, copia de seguridad y recuperación
• Capítulo 12: Preferencias y configuración avanzada