Cómo funciona
Cómo funciona: el puente, el motor por sesión, los tokens de lanzamiento, la concesión de licencia firmada, las comprobaciones periódicas, los asientos, la regla Origin y dónde se guardan las credenciales.
SQLly Embedded separa SQLly en dos mitades: la que necesita secretos y la que no. La interfaz de SQLly se ejecuta en el navegador de tu usuario como WebAssembly. Todo lo que toca una base de datos se ejecuta en tu servidor, dentro del puente de SQLly y los motores que este inicia. Tu aplicación web va junto al puente y le indica quién puede abrir SQLly y con qué conexiones. Esta página explica cada pieza y por qué está construida así.
La arquitectura
Por qué la separación
- Los secretos permanecen del lado del servidor. Un navegador no puede esconderle una contraseña de base de datos a su propio usuario. Así que el navegador nunca recibe una: obtiene una lista de conexiones, envía tramas de consulta y el puente las ejecuta con credenciales que solo tiene el servidor.
- Tu aplicación sigue encargándose de la identidad. El puente no tiene cuentas de usuario. Tu aplicación ya sabe quién ha iniciado sesión. Le dice al puente «abrir SQLly para» esto usuario con esto perfil" emitiendo un token de lanzamiento, y el puente confía en ese token.
- Un motor por sesión. Cada pestaña del navegador obtiene su propio
sqlly-cliproceso, así que las sesiones nunca comparten estado de conexión, transacciones ni tablas temporales, y un fallo solo tumba una pestaña, no el puente.
Dentro del puente
sqlly-bridge embedded hay un solo proceso con tres funciones:
| Trabajo | Escucha en | Se comunica con |
|---|---|---|
| Proxy del navegador: acepta un WebSocket por cada pestaña de SQLly, comprueba su Origin y su token de lanzamiento, inicia un motor con el perfil del token y retransmite las tramas en ambos sentidos. | --bind, predeterminado 0.0.0.0:8444, ruta /proxy | Navegadores (pon TLS delante) |
| API de gestión: perfiles, tokens de lanzamiento, asientos, pruebas de conexión, estado de licencia y el historial de auditoría de consultas. Referencia. | --manage-bind, predeterminado 127.0.0.1:8445 | Solo el lado del servidor de tu aplicación, con un token de portador |
| Monitor de licencias: se conecta con sqlly.app al iniciar y cada 20 minutos (conectado), o vuelve a leer el archivo de licencia cada minuto (sin conexión), y mueve el puente entre estados de licencia. | Nada | sqlly.app a través de HTTPS (solo conectado) |
Su directorio de estado (--state-dir, creado con permisos solo para el propietario en Linux y macOS) guarda cada perfil como profiles/<id>.json, la última concesión de licencia válida (license.json), la clave de una instalación vinculada (license-key, modo 0600), los archivos de credenciales por sesión que entrega a sus motores, y el registro de auditoría de consultas (queries.jsonl: cada consulta que se ejecutó en una sesión, con su texto SQL). Haz una copia de seguridad y guárdalo con el mismo cuidado que un archivo de contraseñas, porque lo es. Dónde ponerlo y qué necesita Windows.
Perfiles: lo que un usuario puede ver
A perfil es un documento de credenciales de SQLly con nombre: el mismo formato JSON que la app de escritorio de SQLly importa y exporta. Enumera conexiones (servidor, base de datos, motor, autenticación, TLS, reglas de seguridad) y las etiquetas de cliente, proyecto y entorno que les dan color y las agrupan. Tu aplicación almacena perfiles con PUT /manage/profiles/{id}. El puente valida el documento entero de antemano y reporta todos los problemas de golpe, así que una errata como "pasword" falla de manera evidente en lugar de ser ignorado.
Los usuarios no pertenecen a perfiles en el puente. Cada arranque designa uno. Da a los analistas un perfil de solo lectura (una etiqueta con only_allow_select, o block_all_but_select en la conexión: el motor no admite nada más que SELECT antes de llegar a la base de datos) y otro para el personal de soporte, o crea un perfil por cliente en una app multiinquilino. Los motores basados en archivos (SQLite, DuckDB) se rechazan a menos que el puente se inicie con --allow-file-engines, porque dan a los usuarios acceso a archivos en el host puente. Para limitar las conexiones de alguien, crea otro perfil. Al abrir una sesión, el navegador recibe el catálogo: nombres de conexión, motores, bases de datos y etiquetas, con todos los secretos eliminados. Los cambios en un perfil se aplican en el próximo inicio. Las sesiones ya abiertas conservan el catálogo con el que empezaron.
La vida de una sesión
- Un usuario con la sesión iniciada abre la página de SQLly en tu aplicación.
- Tu servidor llama
POST /manage/tokenscon tu id para el usuario y el perfil que debería recibir, y opcionalmente qué abrir: pestañas de consulta con su script, conexión, valores de parámetros y cursor (contexto de inicio). - El puente verifica la licencia y el número de asientos, captura el perfil y devuelve un token aleatorio, su fecha de vencimiento y la URL del proxy público.
- Tu servidor devuelve la página de SQLly (
web/index.html) con dos variables globales establecidas antesboot.js:SQLLY_PROXY_URLySQLLY_PROXY_TOKEN. - SQLly abre
wss://…/proxy?token=…. El puente verifica, en orden: elOrigin(rechazado en la actualización con un 403), el token, la licencia, las sesiones abiertas del usuario y su propio límite de sesiones. Un navegador no puede saber por qué falló una actualización, así que cada rechazo posterior a la verificación de origen se entrega por el socket abierto como unerrormensaje con la razón, seguido del código de cierre4000 + HTTP status(4401 token desconocido o caducado, 4503 licencia no válida, 4429 límite de sesiones); SQLly muestra la frase. - El puente escribe las credenciales del perfil en un archivo privado por sesión y comienza
sqlly-clien modo motor con él. - El navegador recibe un saludo con el catálogo de conexiones sin secretos y el estado actual de la licencia. La primera sesión de un token emitido con contexto de lanzamiento también recibe las pestañas que hay que abrir; SQLly las carga, pero no ejecuta nada.
- De aquí en adelante, las solicitudes de SQLly (conectar, ejecutar, cancelar, obtener metadatos para IntelliSense, paginar resultados) viajan como tramas binarias. El puente las reenvía al motor y registra cada consulta y cada edición de filas en su registro de auditoría, y las rechaza con un mensaje si la licencia deja de ser válida.
Asientos y sesiones
A puesto es un ID de usuario distinto que tiene una sesión abierta o un token de lanzamiento sin caducar. Los asientos son concurrentes, no nominales: cuando se cierra la última pestaña de un usuario y expira su último token, el asiento queda libre inmediatamente y otra persona puede usarlo. El puente cuenta los asientos de todos los puentes de la licencia, porque sqlly.app informa de los usuarios que hay en otras instancias en cada registro.
- Generación para un usuario que ya tiene un asiento siempre tiene éxito. La creación para un usuario nuevo cuando todos los asientos están ocupados falla con
409 seat_limit, por lo que tu aplicación puede mostrar un mensaje claro. - Cada asiento puede contener
sessionsPerSeatpestañas abiertas: cuatro en planes de pago, una en la prueba. Una pestaña de más recibe el aviso y se cierra (código 4429). El puente hace ping a cada pestaña y elimina la que siga en silencio 90 segundos, así que una pestaña perdida por un portátil en suspensión libera su sesión por sí sola; cuando un usuario cierra su última pestaña, sus tokens de lanzamiento caducan en un plazo de dos minutos. DELETE /manage/seats/{user}revoca los tokens de un usuario y cierra sus sesiones. Llámalo cuando alguien cierre sesión en tu aplicación o pierda el acceso.- El id de usuario es el que pases. Usa un id estable y opaco (una clave de base de datos o un hash) si prefieres no enviar direcciones de correo: los ids que ocupan asientos se notifican a sqlly.app para poder contar los asientos entre puentes.
Quién puede conectarse: la regla de Origin
Cada licencia está vinculada a un dominio. El puente acepta un WebSocket del navegador únicamente cuando su Origin encabezado es ese dominio o cualquier subdominio del mismo (de cualquier profundidad, esquema o puerto), o localhost / 127.0.0.1 / [::1] mientras --allow-localhost-origins esté activado (el valor predeterminado, para desarrollo). Una licencia sin dominio vinculado admite solo localhost. Vincula el dominio en tu página Embedded, o inicia el puente una vez con --domain.
La API de gestión no envía encabezados CORS en absoluto. Es de servidor a servidor: un navegador en otro origen no puede llamarla, y de todos modos debería estar vinculada al loopback.
Cómo se aplica la licencia
El puente confía en una sola cosa: una concesión de licencia, un JWS compacto que sqlly.app firma con ES384 (ECDSA P-384). La clave de verificación está compilada en el puente. Cada límite (asientos, sesiones por asiento, instancias del puente, dominio, fin del período, días de gracia, funciones) se lee de los claims firmados de la concesión. El JSON sin firmar que lo rodea es solo informativo.
Licencias conectadas
- Al inicio y cada 20 minutos el puente envía
POST /api/embedded/checkincon su clave de licencia, su id de instancia, un nonce nuevo de 32 bytes, su versión y nombre de host, el dominio para el que se inició y los ids de usuario que ahora mismo ocupan asientos. - La concesión de la respuesta debe validar contra la clave compilada en el binario, devolver ese nonce, nombrar esta instancia y la misma licencia, y emitirse dentro de los 5 minutos del reloj del puente. Una respuesta repetida o falsificada falla estas comprobaciones y cuenta como un check-in fallido. Mantén el reloj del host en hora (NTP).
- Un permiso es válido durante 40 minutos. Si no se puede acceder a sqlly.app, el puente sigue funcionando con su último permiso válido hasta que caduca, y luego se detiene obsoleto y se niega a trabajar hasta el próximo registro con éxito, sin necesidad de reiniciar. Un puente reiniciado durante una caída parte de su concesión en caché solo mientras esta no haya caducado.
- Cada licencia conectada permite varias instancias a la vez (uno por defecto). Un segundo puente con la misma clave se registra pero no se admite mientras el primero siga reportándose. Un puente que se detiene limpiamente libera su espacio de inmediato; uno que muere lo libera 40 minutos después.
Licencias sin conexión
Una licencia fuera de línea es un archivo ({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }) que descargas de sqlly.app una vez configurado su dominio. La concesión que lleva es de larga duración: caduca al final del período más los días de gracia. El puente la verifica localmente, nunca contacta con ningún servidor de SQLly y vuelve a leer el archivo cada minuto, así que renovar significa reemplazar el archivo. Las licencias sin conexión no tienen límite de instancias.
Instalaciones vinculadas
Un puente iniciado sin clave y sin archivo está sin licencia: la API de gestión funciona (puedes configurar y probar perfiles) pero se rechazan los lanzamientos. Tu aplicación de administración puede entonces vincular la instalación sin que nadie copie una clave: pide a sqlly.app un código de enlace, el propietario de la licencia lo aprueba en su navegador y la aplicación recibe una clave emitida solo para esta instalación y se la entrega al puente con PUT /manage/license. El puente la verifica, la guarda y sigue usándola entre reinicios. Cada instalación vinculada tiene su propia clave, así que el propietario puede revocar una sin tocar las demás. Cómo construirlo.
Cuando la licencia no es válida
En cada estado excepto ok y grace, el puente mantiene conectados los sockets abiertos, pero responde a cada frame de solicitud con un fallo que lleva una frase clara ("…no pudo confirmar su licencia con sqlly.app durante 40 minutos; pide a tu administrador que lo revise."). El cliente SQLly muestra esa frase en su línea de estado y como notificación, para que los usuarios sepan por qué. A las sesiones nuevas se les comunica la misma frase y se cierran (código 4503), y los tokens de lanzamiento se rechazan con 503 license_not_ok. Durante los 15 días de gracia tras el fin de un periodo, todo sigue funcionando, pero todos los usuarios ven una cuenta regresiva. Cada estado, explicado.
Qué sale de tu servidor
| Enviado a sqlly.app al registrarse | Nunca se envía a ningún lado |
|---|---|
| Clave de licencia · id de instancia del puente · versión del puente · nombre de host · dominio solicitado · ids de usuario con asientos · número de sesiones abiertas | Consultas · resultados · nombres y hosts de bases de datos · credenciales · perfiles · cualquier cosa que escriban tus usuarios |
Las licencias sin conexión no envían nada. El navegador solo se comunica con tu aplicación y tu puente.