Eigene App entwickeln

Schritt für Schritt: Steuere die SQLly-Embedded-Bridge aus deiner eigenen Web-App heraus – Profile speichern, Launch-Tokens ausstellen, den Browser-Build ausliefern, Plätze freigeben und Installationen verknüpfen.

Die Beispiel-App ist ein Stellvertreter für dein Produkt. Alles, was sie tut, läuft über die Brücke Management-API, sodass jeder serverseitige Stack sie ersetzen kann: Node, ASP.NET, Django, Rails, Go, PHP. Diese Seite geht jeden Job durch, den die Beispiel-App erledigt, und zeigt, wie du ihn in deiner eigenen App erledigst. Es gibt Beispiele in JavaScript (Node 20+) und C# (ASP.NET Core), und dieselben Aufrufe funktionieren mit allem, was HTTP und JSON spricht.

Erzeuge einen Client, statt ihn selbst zu schreiben. swagger.json ist eine OpenAPI-3.0-Beschreibung der gesamten Management-API. Gib sie an openapi-generator, NSwag, Kiota oder dein bevorzugtes HTTP-Tool weiter. Die Beispiel-App sample-app/lib/bridge.js ist ebenfalls ein vollständiger handgeschriebener Client in etwa 120 Zeilen.

Was deine App übernimmt

JobIn der Beispiel-AppIn deiner App
Benutzer anmeldenEigene Benutzerdaten-Datei mit Scrypt-Passwörtern (lib/auth.js)Deine bestehende Anmeldung, SSO, Sitzungen
Entscheide, wer welche Verbindungen siehtJedem Benutzer wird ein Profil zugewiesenDeine Rollen, Teams, Mandanten oder Pläne bestimmen die Profil-ID
Verbindungen definierenProfileditor, Registerkarte Labels (lib/credentials.js erstellt das Dokument)Deine Admin-Oberfläche, eine Konfigurationsdatei oder Code, der Dokumente aus deinen Mandantendaten erstellt
SQLly öffnenGET /app/ erzeugt ein Token und injiziert es in index.htmlEine Route, die dasselbe macht (Schritt 4)
Web-Bundle bereitstellen/app/* mit Isolations-HeadernDein statischer Dateiserver oder CDN-Pfad mit denselben Headern (Schritt 5)
Kostenlose BenutzerplätzeBenutzerseite, Platz freigebenRuf es beim Abmelden und beim Entfernen des Zugriffs auf (Schritt 6)
Lizenzstatus anzeigenStatusseiteEin Health-Check oder ein Admin-Widget (Schritt 7)
Lizenz verknüpfenMit sqlly.app verbindenOptional: oder konfiguriere einen Schlüssel oder eine Lizenzdatei (Schritt 8)

1. Führe die Bridge neben deiner App aus

Ohne das Startskript ist die Bridge ein einziger Befehl. Erzeuge das Manage-Token einmal und gib denselben Wert an die Bridge und deine App weiter (über eine Umgebungsvariable oder einen Secret Store, niemals über dein Repository):

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

Deine App spricht mit http://127.0.0.1:8445 mit Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN. Browser erreichen den Proxy-Listener (:8444) über deinen Reverse-Proxy. Produktionsdetails.

2. Ein winziger Management-Client

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. Profile speichern

Ein Profil ist ein SQLly-Dokument mit Anmeldedaten plus ein Anzeigename. Bau es, wie es dir passt: aus Zeilen aus deiner Datenbank, aus einer Vorlage pro Mandant oder aus einem Admin-Formular. GET /manage/engines listet jede Engine-ID, ihren Standardport und welche Anmeldearten sie akzeptiert, sodass ein Formular sie nie hart kodiert.

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' } },
    ],
  },
});
  • Profil-IDs sind 1-64 von A-Z a-z 0-9 _ -. Nutze deinen eigenen stabilen Schlüssel (eine Mandanten-ID, einen Rollennamen).
  • Die Bridge prüft das gesamte Dokument, bevor sie es speichert. Ein ungültiges kommt zurück als 400 invalid_profile mit problems mit Auflistung jedes Fehlers. Unbekannte Schlüssel sind Fehler, daher schleichen sich Tippfehler nie durch.
  • Die Bridge ist der maßgebliche Speicher für Secrets. Wo die Quelle der Wahrheit liegt, ist deine Sache, aber re-PUT Profile, wenn sie sich ändern. Die Beispielanwendung sendet bei jedem Start alle Profile erneut, sodass sich ein frischer Zustandsordner wieder selbst befüllt.
  • Verwende Labels und Sicherheitskennzeichen. only_allow_select in einer Produktionsumgebung oder confirm_data_changes bei einer Verbindung werden von SQLly für jeden, der dieses Profil öffnet, durchgesetzt.

Vor dem Speichern kannst du nachweisen, dass eine Verbindung funktioniert, mit POST /manage/test-connection und einem Dokument, das nur diese eine Verbindung enthält. Fehler werden zurückgegeben als { "ok": false, "message": "<the engine's own error>" } mit HTTP 200, bereit, neben dem Formular angezeigt zu werden.

4. Starte SQLly für einen angemeldeten Benutzer

Das ist die eine Route, die jede Integration braucht. Öffnet ein angemeldeter Nutzer SQLly, stellst du ein Token für ihn aus und gibst das index.html mit zwei gesetzten globalen Variablen vor die boot.js Modul-Tag:

javascript (Express-Stil)
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# (ASP.NET Core Minimal API)
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();
  • Wird auf dem Server pro Anfrage erstellt. Binde das Verwaltungstoken nie in eine Seite ein. Das Starttoken kannst du gefahrlos an den Benutzer weitergeben, für den es ausgestellt wurde: Es öffnet SQLly mit diesem Profil nur für diesen Benutzer und läuft ab (standardmäßig nach 10 Minuten; übergebe ttlSeconds zwischen 10 und 86.400).
  • Wiederverwendung ist in Ordnung. Ein Token funktioniert, bis es abläuft, daher brauchen Seiten-Neuladungen kein neues. Die Beispiel-App speichert den Token jedes Benutzers zwischen und stellt ihn eine Minute vor Ablauf neu aus. Ein erneutes Ausstellen für denselben Benutzer kostet nie einen weiteren Platz.
  • Abfrage öffnen, nicht nur die Arbeitsumgebung. Hinzufügen open zum Mint-Aufruf, um den Benutzer direkt in einem Abfrage-Tab zu öffnen, in dem Skript, Verbindung, Parameterwerte und Cursor schon gesetzt sind. Erzeuge für jeden dieser Starts ein frisches Token: Die Tabs öffnen sich nur für die erste Sitzung, die ein Token startet. SQLly mit einer Abfrage öffnen.
  • Die Benutzer-ID gehört dir. Übergib eine stabile, intransparente ID. Jede unterschiedliche ID zählt als ein Platz, und die IDs mit belegten Plätzen werden beim Check-in an sqlly.app gemeldet.
  • Wenn du das HTML nicht bearbeiten kannst, übergib ?proxy=<url>&token=<token> stattdessen in der Seiten-URL. Injection ist besser, weil das Token dann nicht in der Historie und in den Logs erscheint.
  • Stelle die Seite unter einer URL bereit, die auf / (hier /sqlly/), sodass das relative ./boot.js wird zu deiner Kopie von web/.

5. Das Web-Bundle bereitstellen

Stelle die Dateien in web/ unter demselben Pfad wie die Startseite bereit (/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm, …), mit:

  • Cross-Origin-Opener-Policy: same-origin und Cross-Origin-Embedder-Policy: require-corp auf der Seite und jeder Bundle-Datei. SQLly benötigt SharedArrayBuffer, das Browser nur auf isolierten Seiten aktivieren.
  • application/wasm als Typ für .wasm. Kompression hilft hier richtig: Die Wasm-Datei schrumpft mit Brotli oder gzip um ein Mehrfaches.
  • Wenn deine Seiten eine Content-Security-Policy mitschicken: 'wasm-unsafe-eval' in script-src, der Bridge wss:// Origin in 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' in worker-src (or in script-src, die worker-src falls back to). If it is blocked, large results stay in memory.
  • Die Cross-Origin-Isolation gilt für alles, was die Seite lädt, also liefere das Bundle von deiner eigenen Origin aus und nicht von einem Drittanbieter-CDN ohne CORP-Header.

Die Dateien des Bundles sind mit dem Paket versioniert. Wenn du ein Upgrade durchführst, ersetze web/ und die Bridge zusammen.

6. Sitzplätze verwalten

  • 409 seat_limit bei mint bedeutet, dass jeder Sitzplatz belegt ist. Sag es dem Benutzer klar und biete Administratoren an, einen freizugeben. GET /manage/seats zeigt, wer Plätze belegt und seit wann.
  • Bei Abmeldung freigeben: DELETE /manage/seats/{user} entzieht die Tokens des Benutzers und schließt dessen SQLly-Tabs. Mach dasselbe, wenn du jemandem den Zugriff entziehst. Sonst funktioniert das Token weiter, bis es abläuft.
  • Ein zusätzlicher Tab über sessionsPerSeat wird von der Bridge selbst abgelehnt: Der Socket bekommt die Meldung „<user> hat bereits die maximale Anzahl von SQLly-Sitzungen offen“ und wird mit Code 4429 geschlossen, und SQLly zeigt diesen Satz an.

7. Lizenzstatus anzeigen

GET /manage/status hat alles für ein Admin-Widget oder einen Gesundheitscheck:

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);

Warnung bei allem außer okund behandeln grace als „diese Woche erneuern“. POST /manage/license/checkin erzwingt ein Einchecken (oder liest eine Offline-Datei erneut ein), was für einen Jetzt einchecken Button nach der Behebung des Netzwerkzugangs nützlich ist. Was jeder Zustand bedeutet.

8. Optional: Lizenz aus deiner Admin-Oberfläche verknüpfen

Du kannst die Bridge mit einem Schlüssel oder einer Lizenzdatei konfigurieren und diesen Schritt überspringen. Das Verknüpfen ist für Produkte gedacht, die SQLly Embedded für viele Kunden installieren: Der Admin jedes Kunden verbindet seine Installation mit seiner eigenen sqlly.app-Lizenz mit wenigen Klicks, und nie wird ein Schlüssel kopiert. Starte die Bridge weder mit --license-key noch mit --license-file, dann:

  1. POST https://sqlly.app/api/embedded/links mit einem Anzeigenamen (z. B. "SQLly Embedded on " + hostname). Bewahre die zurückgegebene secret serverseitig. Zeig dem Admin die code und schicke sie an linkUrl.
  2. Der Admin meldet sich bei sqlly.app an, prüft, ob der Code stimmt, wählt eine Lizenz aus und genehmigt die Anfrage.
  3. In der Zwischenzeit abfragen POST https://sqlly.app/api/embedded/links/token mit { linkId, secret } jede pollIntervalSeconds. Es antwortet 202 solange ausstehend, danach 200 einmal mit licenseKey. 410 bedeutet noch einmal von vorn (abgelehnt, abgelaufen oder bereits verwendet).
  4. Gib den Schlüssel direkt an die Bridge weiter: PUT /manage/license { "licenseKey": "…" }. Die Bridge prüft ihn mit sqlly.app, bevor sie ihn speichert, behält ihn über Neustarts hinweg, und der Status zeigt license.source: "linked". Speicher den Schlüssel nicht selbst.
  5. Um die Verbindung zu trennen, DELETE /manage/license: die Bridge gibt ihren Slot frei, widerruft den Schlüssel auf sqlly.app und geht zurück in den nicht lizenzierten Zustand.

Von der Beispiel-App lib/sqllyapp.js und ihre /admin/link Routen implementieren genau dies.

Bevor du auslieferst

  • Das Verwaltungs-Token liegt in der serverseitigen Konfiguration, und die Verwaltungs-API ist an Loopback oder ein privates Netzwerk gebunden.
  • Jeder Start wird serverseitig für einen authentifizierten Benutzer erzeugt, mit einem Profil, das deine Autorisierungsregeln auswählen.
  • Die SQLly-Seite und das Bundle tragen die Isolations-Header, und dein CSP erlaubt die wss:// Ursprung.
  • Abmeldung und Zugriffsentfernung geben den Platz des Benutzers frei.
  • seat_limit und license_not_ok Zeig eine verständliche Meldung, keinen Stack-Trace.
  • Etwas beobachtet GET /manage/status.
  • Gelesen hast du In Produktion gehen.