Crea tu propia aplicación
Paso a paso: controla el puente de SQLly Embedded desde tu propia aplicación web - guarda perfiles, emite tokens de lanzamiento, sirve la versión para navegador, libera puestos y vincula instalaciones.
La aplicación de ejemplo es un sustituto de tu producto. Todo lo que hace pasa a través del puente, API de gestión, así que cualquier pila del lado del servidor puede reemplazarlo: Node, ASP.NET, Django, Rails, Go, PHP. Esta página recorre cada tarea que hace la aplicación de ejemplo y cómo hacerla en tu propia aplicación. Los ejemplos están en JavaScript (Node 20+) y C# (ASP.NET Core), y las mismas llamadas funcionan desde cualquier cliente que hable HTTP y JSON.
Genera un cliente en lugar de escribir uno. swagger.json es una descripción OpenAPI 3.0 de toda la API de gestión. Dásela a openapi-generator, NSwag, Kiota o a tu herramienta HTTP preferida. La app de ejemplo sample-app/lib/bridge.js también es un cliente completo escrito a mano en unas 120 líneas.
Lo que tu app asume
| Trabajo | En la app de ejemplo | En tu app |
|---|---|---|
| Inicia la sesión de tus usuarios | Su propio archivo de usuarios con contraseñas scrypt (lib/auth.js) | Tu inicio de sesión existente, SSO, sesiones |
| Decidir quién ve qué conexiones | A cada usuario se le asigna un perfil | Tus roles, equipos, inquilinos o planes seleccionan el id del perfil |
| Definir conexiones | Editor de perfil, pestaña Etiquetas (lib/credentials.js genera el documento) | Tu interfaz de administrador, un archivo de configuración o código que construye documentos a partir de los datos de tu inquilino |
| Abrir SQLly | GET /app/ genera un token y lo inyecta en index.html | Una ruta que hace lo mismo (paso 4) |
| Servir el paquete web | /app/* con encabezados de aislamiento | Tu servidor de archivos estáticos o ruta CDN con las mismas cabeceras (paso 5) |
| Puestos gratuitos | Página de usuarios, Liberar asiento | Llámalo al cerrar sesión y cuando se retire el acceso (paso 6) |
| Mostrar el estado de la licencia | Página de estado | Una comprobación de estado o un widget de administración (paso 7) |
| Vincular a una licencia | Conéctate a sqlly.app | Opcional: o configura una clave o un archivo de licencia (paso 8) |
1. Ejecuta el puente junto a tu aplicación
Sin el script de inicio, el puente es un solo comando. Genera el token de gestión una vez y da el mismo valor al puente y a tu aplicación (una variable de entorno o un almacén de secretos, nunca a tu repositorio):
export SQLLY_EMBEDDED_MANAGE_TOKEN="$(openssl rand -base64 24)"
export SQLLY_EMBEDDED_LICENSE_KEY=sqe_… # or SQLLY_EMBEDDED_LICENSE_FILE, or neither and link later
./bin/sqlly-bridge embedded \
--domain portal.example.com \
--public-url wss://portal.example.com/sqlly/proxy \
--manage-bind 127.0.0.1:8445 \
--state-dir /var/lib/sqlly-embedded
Tu aplicación se comunica con http://127.0.0.1:8445 con Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN. Los navegadores se conectan al listener del proxy (:8444) a través de tu proxy inverso. Detalles de producción.
2. Un pequeño cliente de gestión
javascript (node 20+)const BRIDGE = process.env.SQLLY_BRIDGE_URL ?? 'http://127.0.0.1:8445';
const TOKEN = process.env.SQLLY_EMBEDDED_MANAGE_TOKEN;
export async function bridge(method, path, body) {
const res = await fetch(BRIDGE + path, {
method,
headers: {
authorization: `Bearer ${TOKEN}`,
...(body ? { 'content-type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return null;
const json = await res.json().catch(() => null);
if (!res.ok) {
// Every error is { error, message } (+ problems for invalid documents).
throw Object.assign(new Error(json?.message ?? `bridge HTTP ${res.status}`),
{ code: json?.error, status: res.status, problems: json?.problems });
}
return json;
}
c# (asp.net core)
builder.Services.AddHttpClient("sqlly-bridge", c =>
{
c.BaseAddress = new Uri(builder.Configuration["Sqlly:BridgeUrl"] ?? "http://127.0.0.1:8445");
c.DefaultRequestHeaders.Authorization =
new("Bearer", builder.Configuration["Sqlly:ManageToken"]);
});
public sealed record BridgeError(string Error, string Message, string[]? Problems);
public sealed record MintedToken(string Token, DateTimeOffset ExpiresAt, string ProxyUrl,
string User, string Profile, int SeatsUsed, int Seats);
3. Guardar perfiles
Un perfil es un documento de credenciales de SQLly más un nombre para mostrar. Constrúyelo como mejor te convenga: a partir de filas en tu base de datos, de una plantilla por inquilino, o de un formulario de administrador. GET /manage/engines enumera cada id de motor, su puerto predeterminado y qué tipos de inicio de sesión acepta, para que ningún formulario los tenga que escribir a mano.
await bridge('PUT', '/manage/profiles/acme-analysts', {
name: 'Acme analysts',
credentials: {
format: 'sqlly-credentials',
version: 1,
clients: [{ name: 'Acme', color: '#1E88E5' }],
environments: [{ name: 'Production', safety: { only_allow_select: true } }],
sql_auth_accounts: [{ name: 'Reader', username: 'acme_ro', password: secrets.acmeReader }],
connections: [
{ name: 'Orders', engine: 'postgres', server: 'pg1.internal', database: 'orders',
environment: 'production', client: 'Acme',
authentication: { type: 'sql-login', account: 'Reader' }, tls: { mode: 'verify-full' } },
],
},
});
- Los ids de perfil son 1-64 de
A-Z a-z 0-9 _ -. Usa tu propia clave estable (un ID de inquilino, un nombre de rol). - El puente valida el documento completo antes de guardarlo. Si es incorrecto, vuelve como
400 invalid_profileconproblemslistando cada error. Las claves desconocidas son errores, así que ningún typo se cuela. - El puente es el almacén de referencia de los secretos. Mantén la fuente de la verdad donde quieras, pero re-
PUTperfiles cuando cambie. La aplicación de ejemplo vuelve a enviar cada perfil al inicio, así que un directorio de estado nuevo se repuebla solo. - Usa etiquetas y flags de seguridad.
only_allow_selecten un entorno de Producción, oconfirm_data_changesen una conexión, SQLly los aplica a todos los que abran ese perfil.
Antes de guardar, puedes comprobar que una conexión funciona con POST /manage/test-connection y un documento que contenga solo esa conexión. Los fallos llegan como { "ok": false, "message": "<the engine's own error>" } con HTTP 200, listo para mostrar junto al formulario.
4. Iniciar SQLly para un usuario con la sesión iniciada
Esta es la ruta que necesita toda integración. Cuando un usuario con la sesión iniciada abre SQLly, genérale un token y devuelve el paquete index.html con dos variables globales configuradas antes las boot.js etiqueta de módulo:
import { readFile } from 'node:fs/promises';
const ISOLATION = {
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp',
};
const BOOT_TAG = '<script type="module" src="./boot.js"></script>';
// JSON for an inline script: never let a value close the tag.
const js = (v) => JSON.stringify(v).replace(/</g, '\\u003c');
app.get('/sqlly/', requireSignIn, async (req, res) => {
const profile = profileFor(req.user); // your rule: role, team, tenant…
let minted;
try {
minted = await bridge('POST', '/manage/tokens', { user: req.user.id, profile });
} catch (err) {
if (err.code === 'seat_limit') return res.status(409).send('All SQLly seats are in use right now.');
if (err.code === 'license_not_ok') return res.status(503).send(err.message);
throw err;
}
const html = (await readFile('web/index.html', 'utf8')).replace(BOOT_TAG,
`<script>globalThis.SQLLY_PROXY_URL=${js(minted.proxyUrl)};` +
`globalThis.SQLLY_PROXY_TOKEN=${js(minted.token)};</script>` + BOOT_TAG);
res.set(ISOLATION).set('Cache-Control', 'no-store').type('html').send(html);
});
c# (api mínima de asp.net core)
app.MapGet("/sqlly/", async (HttpContext http, IHttpClientFactory clients, IWebHostEnvironment env) =>
{
var user = http.User.FindFirst("sub")!.Value;
var bridge = clients.CreateClient("sqlly-bridge");
var reply = await bridge.PostAsJsonAsync("/manage/tokens", new { user, profile = ProfileFor(http.User) });
if (!reply.IsSuccessStatusCode)
{
var error = await reply.Content.ReadFromJsonAsync<BridgeError>();
return Results.Text(error?.Message ?? "SQLly is unavailable.", statusCode: (int)reply.StatusCode);
}
var minted = (await reply.Content.ReadFromJsonAsync<MintedToken>())!;
const string bootTag = "<script type=\"module\" src=\"./boot.js\"></script>";
// JsonSerializer escapes < > & by default, so the values can't close the tag.
var globals = $"<script>globalThis.SQLLY_PROXY_URL={JsonSerializer.Serialize(minted.ProxyUrl)};" +
$"globalThis.SQLLY_PROXY_TOKEN={JsonSerializer.Serialize(minted.Token)};</script>";
var html = (await File.ReadAllTextAsync(Path.Combine(env.ContentRootPath, "sqlly-web", "index.html")))
.Replace(bootTag, globals + bootTag);
http.Response.Headers["Cross-Origin-Opener-Policy"] = "same-origin";
http.Response.Headers["Cross-Origin-Embedder-Policy"] = "require-corp";
http.Response.Headers.CacheControl = "no-store";
return Results.Content(html, "text/html");
}).RequireAuthorization();
- Se genera en el servidor, uno por solicitud. Nunca pongas el token de administración en una página. El token de lanzamiento puedes entregarlo sin riesgo al usuario para el que se creó: abre SQLly con ese perfil solo para ese usuario y expira (10 minutos por defecto; pasa
ttlSecondsentre 10 y 86,400). - Está bien reutilizarlo. Un token funciona hasta que expira, así que recargar la página no necesita uno nuevo. La aplicación de ejemplo guarda en caché el token de cada usuario y vuelve a generarlo un minuto antes de que expire. Volver a generar un token para el mismo usuario nunca ocupa otro asiento.
- Abre una consulta, no solo el entorno de trabajo. Añadir
openen la llamada a mint para que el usuario aterrice en una pestaña de consulta con el script, la conexión, los valores de los parámetros y el cursor ya configurados. Genera un token nuevo para cada uno de esos lanzamientos: las pestañas solo se abren en la primera sesión que inicia un token. Abrir SQLly en una consulta. - El id de usuario lo eliges tú. Pasa un id estable y opaco. Los asientos cuentan ids distintos, y los ids que ocupan asientos se reportan a sqlly.app al hacer el check-in.
- Si no puedes editar el HTML, pasa
?proxy=<url>&token=<token>en la URL de la página. Inyectarlo es mejor, porque el token no queda en el historial ni en los registros. - Sirve la página en una URL que termine en
/(aquí/sqlly/) para que el./boot.jsrelativo del paquete se resuelva a tu copia deweb/.
5. Servir el paquete web
Sirve los archivos en web/ en la misma ruta que la página de inicio (/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm, …), con:
Cross-Origin-Opener-Policy: same-originyCross-Origin-Embedder-Policy: require-corpen la página y en cada archivo del paquete. SQLly necesitaSharedArrayBuffer, que los navegadores solo habilitan en páginas aisladas.application/wasmcomo tipo para.wasm. Aquí la compresión ayuda mucho: con Brotli o gzip el archivo wasm queda varias veces más pequeño.- Si tus páginas envían una Content-Security-Policy:
'wasm-unsafe-eval'enscript-src, el origen del puentewss://enconnect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage byspill-worker.js, a worker script, which nonces don't cover: allow it with'self'enworker-src(or inscript-src, queworker-srcfalls back to). If it is blocked, large results stay in memory. - El aislamiento de origen cruzado se aplica a todo lo que la página carga, por lo que sirve el paquete desde tu propio origen en lugar de un CDN de terceros sin encabezados CORP.
Los archivos del bundle se versionan con el paquete. Cuando actualices, reemplaza web/ y el puente juntos.
6. Gestionar asientos
409 seat_limiten mint significa que todos los asientos están en uso. Explícaselo al usuario con claridad y, para los administradores, ofrece liberar uno.GET /manage/seatsenumera quién tiene los asientos y desde cuándo.- Liberar al cerrar sesión:
DELETE /manage/seats/{user}revoca los tokens del usuario y cierra sus pestañas de SQLly. Haz lo mismo cuando le quites el acceso a alguien. De lo contrario, su token sigue funcionando hasta que expire. - Una pestaña extra más allá
sessionsPerSeates rechazado por el propio puente: al socket se le dice "<user> ya tiene el número máximo de sesiones SQLly abiertas" y se cierra con el código 4429, y SQLly muestra esa frase.
7. Mostrar estado de la licencia
GET /manage/status tiene todo lo necesario para un widget de administración o un chequeo de estado:
const s = await bridge('GET', '/manage/status');
// s.license.state: ok | grace | stale | not_admitted | expired | revoked | domain_mismatch | unlicensed
// s.license.message: the sentence your users see when something is wrong
// s.license.daysRemaining, s.license.planName, s.seatsUsed / s.license.seats
const healthy = ['ok', 'grace'].includes(s.license.state);
Avisar ante cualquier cosa distinta de ok, y tratar grace como «renovar esta semana». POST /manage/license/checkin fuerza un registro (o vuelve a leer un archivo sin conexión), lo cual es útil para un Conectar ahora botón después de arreglar el acceso a la red. Lo que significa cada estado.
8. Enlaza una licencia desde tu interfaz de administración (opcional)
Puedes configurar el puente con una clave o archivo de licencia y omitir esto. La vinculación es para productos que instalan SQLly Embedded para muchos clientes: cada administrador del cliente conecta su instalación a su propia licencia de sqlly.app con unos pocos clics, y nunca se copia ninguna clave. Inicia el puente sin ninguna de las dos --license-key ni --license-file, luego:
POST https://sqlly.app/api/embedded/linkscon un nombre para mostrar (por ejemplo"SQLly Embedded on " + hostname). Mantén elsecretdel lado del servidor. Muestra al administrador elcodey envíalos alinkUrl.- El administrador inicia sesión en sqlly.app, comprueba que el código coincida, elige una licencia y aprueba.
- Mientras tanto, sondea
POST https://sqlly.app/api/embedded/links/tokencon{ linkId, secret }cadapollIntervalSeconds. Responde202mientras está pendiente, luego200una vez conlicenseKey.410significa comenzar de nuevo (denegado, expirado o ya usado). - Entrega la clave directamente al puente:
PUT /manage/license { "licenseKey": "…" }. El puente la verifica con sqlly.app antes de guardarla, la conserva entre reinicios y el estado muestralicense.source: "linked". No guardes la clave por tu cuenta. - Para desconectar,
DELETE /manage/license: el puente libera su ranura, revoca la clave en sqlly.app y vuelve a estar sin licencia.
El archivo lib/sqllyapp.js y sus /admin/link rutas de la aplicación de ejemplo implementan exactamente esto.
Antes de lanzar
- El token de gestión vive en la configuración del servidor y la API de gestión está vinculada a loopback o a una red privada.
- Cada lanzamiento se genera del lado del servidor para un usuario autenticado, con el perfil que elijan tus reglas de autorización.
- La página y el paquete de SQLly llevan los encabezados de aislamiento, y tu CSP permite el
wss://origen del puente. - Cerrar sesión y eliminar el acceso liberan el asiento del usuario.
seat_limitylicense_not_okmuestra un mensaje claro, no una traza de la pila.- Algo vigila
GET /manage/status. - Has leído Ir a producción.