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

TrabajoEn la app de ejemploEn tu app
Inicia la sesión de tus usuariosSu propio archivo de usuarios con contraseñas scrypt (lib/auth.js)Tu inicio de sesión existente, SSO, sesiones
Decidir quién ve qué conexionesA cada usuario se le asigna un perfilTus roles, equipos, inquilinos o planes seleccionan el id del perfil
Definir conexionesEditor 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 SQLlyGET /app/ genera un token y lo inyecta en index.htmlUna ruta que hace lo mismo (paso 4)
Servir el paquete web/app/* con encabezados de aislamientoTu servidor de archivos estáticos o ruta CDN con las mismas cabeceras (paso 5)
Puestos gratuitosPágina de usuarios, Liberar asientoLlámalo al cerrar sesión y cuando se retire el acceso (paso 6)
Mostrar el estado de la licenciaPágina de estadoUna comprobación de estado o un widget de administración (paso 7)
Vincular a una licenciaConéctate a sqlly.appOpcional: 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_profile con problems listando 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-PUT perfiles 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_select en un entorno de Producción, o confirm_data_changes en 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:

javascript (estilo express)
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 ttlSeconds entre 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 open en 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.js relativo del paquete se resuelva a tu copia de web/.

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-origin y Cross-Origin-Embedder-Policy: require-corp en la página y en cada archivo del paquete. SQLly necesita SharedArrayBuffer, que los navegadores solo habilitan en páginas aisladas.
  • application/wasm como 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' en script-src, el origen del puente wss:// en connect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage by spill-worker.js, a worker script, which nonces don't cover: allow it with 'self' en worker-src (or in script-src, que worker-src falls 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_limit en 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/seats enumera 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á sessionsPerSeat es 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:

  1. POST https://sqlly.app/api/embedded/links con un nombre para mostrar (por ejemplo "SQLly Embedded on " + hostname). Mantén el secret del lado del servidor. Muestra al administrador el code y envíalos a linkUrl.
  2. El administrador inicia sesión en sqlly.app, comprueba que el código coincida, elige una licencia y aprueba.
  3. Mientras tanto, sondea POST https://sqlly.app/api/embedded/links/token con { linkId, secret } cada pollIntervalSeconds. Responde 202 mientras está pendiente, luego 200 una vez con licenseKey. 410 significa comenzar de nuevo (denegado, expirado o ya usado).
  4. 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 muestra license.source: "linked". No guardes la clave por tu cuenta.
  5. 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_limit y license_not_ok muestra un mensaje claro, no una traza de la pila.
  • Algo vigila GET /manage/status.
  • Has leído Ir a producción.