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
| Job | In der Beispiel-App | In deiner App |
|---|---|---|
| Benutzer anmelden | Eigene Benutzerdaten-Datei mit Scrypt-Passwörtern (lib/auth.js) | Deine bestehende Anmeldung, SSO, Sitzungen |
| Entscheide, wer welche Verbindungen sieht | Jedem Benutzer wird ein Profil zugewiesen | Deine Rollen, Teams, Mandanten oder Pläne bestimmen die Profil-ID |
| Verbindungen definieren | Profileditor, Registerkarte Labels (lib/credentials.js erstellt das Dokument) | Deine Admin-Oberfläche, eine Konfigurationsdatei oder Code, der Dokumente aus deinen Mandantendaten erstellt |
| SQLly öffnen | GET /app/ erzeugt ein Token und injiziert es in index.html | Eine Route, die dasselbe macht (Schritt 4) |
| Web-Bundle bereitstellen | /app/* mit Isolations-Headern | Dein statischer Dateiserver oder CDN-Pfad mit denselben Headern (Schritt 5) |
| Kostenlose Benutzerplätze | Benutzerseite, Platz freigeben | Ruf es beim Abmelden und beim Entfernen des Zugriffs auf (Schritt 6) |
| Lizenzstatus anzeigen | Statusseite | Ein Health-Check oder ein Admin-Widget (Schritt 7) |
| Lizenz verknüpfen | Mit sqlly.app verbinden | Optional: 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_profilemitproblemsmit 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-
PUTProfile, 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_selectin einer Produktionsumgebung oderconfirm_data_changesbei 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:
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
ttlSecondszwischen 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
openzum 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.jswird zu deiner Kopie vonweb/.
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-originundCross-Origin-Embedder-Policy: require-corpauf der Seite und jeder Bundle-Datei. SQLly benötigtSharedArrayBuffer, das Browser nur auf isolierten Seiten aktivieren.application/wasmals 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'inscript-src, der Bridgewss://Origin inconnect-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'inworker-src(or inscript-src, dieworker-srcfalls 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_limitbei mint bedeutet, dass jeder Sitzplatz belegt ist. Sag es dem Benutzer klar und biete Administratoren an, einen freizugeben.GET /manage/seatszeigt, 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
sessionsPerSeatwird 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:
POST https://sqlly.app/api/embedded/linksmit einem Anzeigenamen (z. B."SQLly Embedded on " + hostname). Bewahre die zurückgegebenesecretserverseitig. Zeig dem Admin diecodeund schicke sie anlinkUrl.- Der Admin meldet sich bei sqlly.app an, prüft, ob der Code stimmt, wählt eine Lizenz aus und genehmigt die Anfrage.
- In der Zwischenzeit abfragen
POST https://sqlly.app/api/embedded/links/tokenmit{ linkId, secret }jedepollIntervalSeconds. Es antwortet202solange ausstehend, danach200einmal mitlicenseKey.410bedeutet noch einmal von vorn (abgelehnt, abgelaufen oder bereits verwendet). - 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 zeigtlicense.source: "linked". Speicher den Schlüssel nicht selbst. - 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_limitundlicense_not_okZeig eine verständliche Meldung, keinen Stack-Trace.- Etwas beobachtet
GET /manage/status. - Gelesen hast du In Produktion gehen.