So funktioniert es

Die Funktionsweise: die Bridge, die Engine pro Sitzung, Starttoken, die signierte Lizenzfreigabe, Check-ins, Plätze, die Origin-Regel und wo die Zugangsdaten liegen.

SQLLY Embedded teilt SQLLY in die Hälfte, die Geheimnisse braucht, und die, die sie nicht braucht. Die SQLLY-Benutzeroberfläche läuft als WebAssembly im Browser deiner Nutzer. Alles, was eine Datenbank berührt, läuft auf deinem Server, in der SQLLY-Bridge und den Engines, die sie startet. Deine Web-App steht neben der Bridge und sagt ihr, wer SQLLY mit welchen Verbindungen öffnen darf. Diese Seite erklärt jedes bewegliche Teil und warum es so gebaut ist.

Die Architektur

SQLly Embedded Architektur Der Browser deiner Benutzer lädt SQLly von deiner Web-App und verbindet sich über einen WebSocket mit der SQLly-Bridge. Deine App steuert die Bridge über ihre Loopback-Management-API. Die Bridge führt eine SQLly-Engine pro Sitzung aus, die sich mit deinen Datenbanken verbindet. Die Bridge prüft ihre Lizenz alle 20 Minuten bei sqlly.app. deine Benutzer dein Server sqlly.app Browser SQLly (WebAssembly) keine Passwörter hier Deine Webanwendung Anmeldung · wer welches Profil bekommt · stellt web/ bereit sqlly-bridge eingebettet :8444 /proxy (Browser, wss) :8445 /manage (deine App, Loopback) Profile · Tokens · Plätze · Lizenz sqlly-cli-Engine eins pro Sitzung Deine Datenbanken jede SQLly-Engine sqlly.app unterzeichnet eine Lizenz Zuschuss pro Check-in https wss Bearer-Token stdio Check-in alle 20 Minuten
Blaue Pfade tragen die Arbeit deiner Nutzer; der gestrichelte Pfad ist der Lizenz-Check-in, der keine Abfragen, Ergebnisse oder Zugangsdaten überträgt. Offline-Lizenzen lassen ihn ganz weg.

Warum die Aufteilung

  • Secrets bleiben serverseitig. Ein Browser kann ein Datenbankpasswort vor seinem eigenen Benutzer nicht geheim halten. Also bekommt der Browser nie eines. Er bekommt eine Verbindungsliste, schickt Abfrage-Frames, und die Bridge führt sie mit Zugangsdaten aus, die nur der Server hält.
  • Deine App behält die Kontrolle über die Identität. Die Bridge hat keine Benutzerkonten. Deine App weiß bereits, wer angemeldet ist. Sie sagt der Bridge „Öffne SQLly für diesen Benutzer mit diesen Profil“, indem sie ein Start-Token erstellt, und die Brücke vertraut dem Token.
  • Eine Engine pro Sitzung. Jeder Browser-Tab erhält seinen eigenen sqlly-cli Prozess, sodass Sitzungen nie Verbindungszustände, Transaktionen oder temporäre Tabellen teilen, und ein Absturz führt nur zum Ausfall eines Tabs, nicht der Bridge.

In der Bridge

sqlly-bridge embedded ist ein Prozess mit drei Jobs:

JobLauscht aufspricht mit
Browser-Proxy: akzeptiert einen WebSocket pro SQLly-Tab, überprüft dessen Origin und Start-Token, startet eine Engine mit dem Profil des Tokens und überträgt Frames in beide Richtungen.--bind, Standard 0.0.0.0:8444, Pfad /proxyBrowser (TLS davor setzen)
Management-API: Profile, Start-Tokens, Sitzplätze, Verbindungstests, Lizenzstatus und der Abfrage-Audit-Trail. Referenz.--manage-bind, Standard 127.0.0.1:8445Nur die Serverseite deiner App, mit einem Bearer-Token
Lizenzmonitor: meldet sich beim Start und alle 20 Minuten bei sqlly.app an (verbunden) oder liest die Lizenzdatei jede Minute erneut (offline) und schaltet die Bridge zwischen den Lizenzzuständen um.Nichtssqlly.app über HTTPS (nur verbunden)

Sein Zustandsverzeichnis (--state-dir, unter Linux und macOS nur für den Eigentümer erstellt) enthält jedes Profil als profiles/<id>.json, die letzte gültige Lizenzvergabe (license.json), den Schlüssel einer verbundenen Installation (license-key, Modus 0600), die pro Sitzung erzeugten Zugangsdaten-Dateien, die es an seine Engines weitergibt, und den Abfrage-Audit-Trail (queries.jsonl: jede Abfrage, die eine Sitzung ausgeführt hat, mit ihrem SQL-Text). Sichere sie und behandle sie so privat wie eine Passwortdatei, denn sie ist eine. Wohin es gehört und was Windows braucht.

Profile: was ein Nutzer sehen kann

A Profil ist ein benanntes SQLly-Credential-Dokument: dasselbe JSON-Format, das die SQLly-Desktop-App importiert und exportiert. Es listet Verbindungen auf (Server, Datenbank, Engine, Authentifizierung, TLS, Sicherheitsregeln) und die Client-, Projekt- und Umgebungs-Labels, die sie einfärben und gruppieren. Deine App speichert Profile mit PUT /manage/profiles/{id}. Die Bridge prüft das gesamte Dokument vorab und meldet alle Probleme auf einmal, sodass ein Tippfehler wie "pasword" laut fehlschlägt anstatt ignoriert zu werden.

Benutzer gehören in der Bridge keinen Profilen an. Jeder Start benennt ein Profil. Gib Analysten ein schreibgeschütztes Profil (ein Label mit only_allow_select, oder block_all_but_select auf der Verbindung: die Engine verweigert alles außer SELECT, bevor es die Datenbank erreicht) und dem Support-Personal ein anderes, oder erstelle ein Profil pro Kunde in einer Multi-Tenant-App. Dateibasierte Engines (SQLite, DuckDB) werden abgelehnt, es sei denn, die Bridge wird mit --allow-file-engines, weil sie den Benutzern Datei-Zugriff auf dem Bridge-Host geben. Erstelle ein weiteres Profil, um jemandem weniger Verbindungen zu geben. Wenn eine Sitzung geöffnet wird, bekommt der Browser die Katalog: Verbindungsnamen, Engines, Datenbanken und Labels, wobei jedes Geheimnis entfernt wird. Das Bearbeiten eines Profils gilt für den nächsten Start. Bereits geöffnete Sitzungen behalten den Katalog, mit dem sie gestartet wurden.

Das Leben einer Sitzung

SQLly für einen Benutzer starten Der Browser fragt deine App nach SQLly. Deine App erstellt ein Start-Token über die Bridge und liefert die SQLly-Seite mit Proxy-URL und Token zurück. Der Browser öffnet eine WebSocket zur Bridge und übermittelt das Token. Die Bridge prüft Origin, Token, Lizenz und Sitzplätze, startet eine Engine mit den Zugangsdaten des Profils und schickt dem Browser ein Hello mit dem Verbindungskatalog und dem Lizenzstatus. Danach fließen Abfrage-Frames vom Browser über Bridge und Engine zur Datenbank und zurück. Browser Deine App Bridge Engine Datenbank 1 geöffnetes SQLly (angemeldet) 2 POST /manage/tokens 3 201 {token, proxyUrl} 4 SQLly-Seite + Token 5 wss /proxy?token=… (Origin geprüft) 6 starten, mit Anmeldedaten 7 hello {catalog, license} - keine Geheimnisse 8 Abfrage-Frame SQL Zeilen 9 Ergebnisse zurück streamen Der Token lässt sich bis zum Ablauf wiederverwenden (bei neuem Laden der Seite); das Schließen des letzten Tabs gibt den Platz sofort frei.
Die Schritte 2-4 sind der einzige Teil, den deine App implementiert. Alles nach dem Öffnen des WebSocket läuft zwischen Browser und Bridge.
  1. Ein angemeldeter Benutzer öffnet die SQLly-Seite in deiner App.
  2. Dein Server kontaktiert POST /manage/tokens mit deiner ID für den Benutzer und dem Profil, das er erhalten soll, und optional, was geöffnet werden soll: Abfrage-Tabs mit ihrem Skript, ihrer Verbindung, ihren Parameterwerten und ihrem Cursor (Startkontext).
  3. Die Bridge prüft die Lizenz und die Anzahl der Sitzplätze, erfasst das Profil und gibt ein zufälliges Token, seine Ablaufzeit und die öffentliche Proxy-URL zurück.
  4. Dein Server liefert die SQLly-Seite zurück (web/index.html) mit zwei vorher gesetzten globalen Variablen boot.js: SQLLY_PROXY_URL und SQLLY_PROXY_TOKEN.
  5. SQLly öffnet wss://…/proxy?token=…. Die Bridge überprüft in folgender Reihenfolge: den Browser Origin (beim Upgrade mit 403 verweigert), das Token, die Lizenz, die offenen Sitzungen des Benutzers und das eigene Sitzungslimit. Ein Browser kann nicht lesen, warum ein Upgrade fehlgeschlagen ist, daher wird jede Ablehnung nach der Origin-Prüfung über den offenen Socket als error Nachricht mit dem Grund geliefert, gefolgt vom Schließcode 4000 + HTTP status (4401 unbekanntes oder abgelaufenes Token, 4503 Lizenz nicht in Ordnung, 4429 Sitzungslimit); SQLly zeigt den Satz an.
  6. Die Bridge schreibt die Zugangsdaten des Profils in eine private pro Sitzung angelegte Datei und startet sqlly-cli damit im Engine-Modus.
  7. Der Browser empfängt ein Hello, das den Verbindungskatalog ohne Secrets und den aktuellen Lizenzstatus enthält. Die erste Sitzung eines Tokens, das mit Startkontext erstellt wurde, bekommt außerdem die zu öffnenden Tabs; SQLly lädt sie, führt aber nichts aus.
  8. Von hier an reisen SQLlys Anfragen (verbinden, ausführen, abbrechen, Metadaten für IntelliSense holen, durch Ergebnisse blättern) als Binär-Frames. Die Bridge reicht sie an die Engine weiter und schreibt jede Abfrage und jede Zeilenänderung in ihre Überwachungspfad, und lehnt sie mit einer Meldung ab, falls die Lizenz ungültig wird.

Lizenzplätze und Sitzungen

A Lizenzplatz ist eine eindeutige Benutzer-ID, die eine offene Sitzung oder ein nicht abgelaufenes Start-Token hat. Plätze gelten gleichzeitig, nicht namentlich: Schließt ein Benutzer den letzten Tab und läuft sein letztes Token ab, wird der Platz sofort frei und jemand anderes kann ihn nutzen. Die Bridge zählt die Plätze über alle Bridges der Lizenz hinweg, denn sqlly.app meldet die Benutzer auf anderen Instanzen bei jedem Check-in.

  • Erstellung für einen Benutzer, der bereits der einen Platz hält, gelingt immer. Das Ausstellen für einen neuen Benutzer, wenn jeder Platz belegt ist, schlägt fehl mit 409 seat_limit, sodass deine App eine klare Meldung anzeigen kann.
  • Jeder Sitzplatz fasst sessionsPerSeat geöffnete Tabs: vier in kostenpflichtigen Plänen, einer in der Testphase. Ein zusätzlicher Tab wird darüber informiert und geschlossen (Code 4429). Die Bridge pingt jeden Tab und trennt einen, der 90 Sekunden lang stumm bleibt, sodass ein Tab, der durch einen schlafenden Laptop verloren geht, seine Sitzung von selbst freigibt; schließt du deinen letzten Tab, laufen deine Start-Token innerhalb von zwei Minuten ab.
  • DELETE /manage/seats/{user} widerruft die Tokens eines Benutzers und schließt dessen Sitzungen. Ruf es auf, wenn sich jemand aus deiner App abmeldet oder den Zugriff verliert.
  • Die Benutzer-ID ist die, die du übergibst. Nimm eine stabile, nicht zurückführbare ID (einen Datenbankschlüssel oder einen Hash), wenn du keine E-Mail-Adressen senden willst: Die IDs, die Plätze halten, werden an sqlly.app gemeldet, damit Plätze über Bridges hinweg gezählt werden können.

Wer darf sich verbinden: die Origin-Regel

Jede Lizenz ist an eine Domain gebunden. Die Bridge akzeptiert ein Browser-WebSocket nur, wenn sein Origin Header diese Domain oder eine beliebige Subdomain davon (beliebige Tiefe, Schema oder Port) ist, oder localhost / 127.0.0.1 / [::1] während --allow-localhost-origins aktiv ist (Standard, für die Entwicklung). Eine Lizenz ohne gebundene Domain lässt nur localhost zu. Binde die Domain auf deiner Embedded-Seite, oder starte die Bridge einmal mit --domain.

Die Verwaltungs-API sendet überhaupt keine CORS-Header. Sie ist Server-zu-Server gedacht: Ein Browser mit anderer Origin kann sie nicht aufrufen, und sie sollte ohnehin nur an Loopback gebunden sein.

Wie die Lizenz durchgesetzt wird

Die Bridge vertraut einer Sache: einer Lizenzgewährung, ein kompaktes JWS, das sqlly.app mit ES384 (ECDSA P-384) signiert. Der Verifizierungsschlüssel ist in die Bridge einkompiliert. Jedes Kontingent (Sitze, Sitzungen pro Sitz, Bridge-Instanzen, Domain, Ende der Laufzeit, Kulanztage, Funktionen) wird aus den signierten Claims der Lizenz gelesen. Das unsignierte JSON darum herum dient nur der Anzeige.

Verbundene Lizenzen

  • Beim Start und alle 20 Minuten sendet die Bridge POST /api/embedded/checkin mit ihrem Lizenzschlüssel, ihrer Instanz-ID, einer frischen 32-Byte-Nonce, ihrer Version und ihrem Hostnamen, der Domäne, für die sie gestartet wurde, und den Benutzer-IDs, die gerade Lizenzplätze belegen.
  • Der Grant der Antwort muss sich gegen den einkompilierten Schlüssel verifizieren lassen, diese Nonce zurückgeben, diese Instanz und dieselbe Lizenz nennen und innerhalb von 5 Minuten relativ zur Uhr der Bridge ausgestellt sein. Eine wiedereingespielte oder gefälschte Antwort fällt durch diese Prüfungen und zählt als fehlgeschlagener Check-in. Halte die Uhr des Hosts richtig (NTP).
  • Ein Grant ist 40 Minuten gültig. Ist sqlly.app nicht erreichbar, arbeitet die Bridge weiter mit dem letzten gültigen Grant, bis dieser abläuft, und geht dann veraltet und verweigert die Arbeit bis zum nächsten erfolgreichen Check-in, ohne dass ein Neustart erforderlich ist. Eine während eines Ausfalls neu gestartete Brücke startet nur mit ihrer zwischengespeicherten Erlaubnis, solange diese noch nicht abgelaufen ist.
  • Jede verbundene Lizenz erlaubt eine bestimmte Anzahl von Bridge- Instanzen gleichzeitig (standardmäßig eine). Eine zweite Bridge mit demselben Schlüssel wird registriert, aber nicht zugelassen, solange die erste sich weiterhin meldet. Eine Bridge, die sauber stoppt, gibt ihren Slot sofort frei. Eine, die abstirbt, gibt ihn 40 Minuten später frei.

Offline-Lizenzen

Eine Offline-Lizenz ist eine Datei ({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }), die du von sqlly.app herunterlädst, sobald deren Domain festgelegt ist. Die darin enthaltene Berechtigung ist langlebig: Sie läuft zum Ende der Laufzeit plus Kulanztagen ab. Die Bridge prüft sie lokal, kontaktiert nie einen SQLly-Server und liest die Datei jede Minute neu, Verlängern heißt also, die Datei auszutauschen. Offline-Lizenzen haben kein Instanzlimit.

Verknüpfte Installationen

Eine Bridge, die ohne Schlüssel und ohne Datei gestartet wird, ist unlizenziert: die Management-API funktioniert (du kannst Profile anlegen und testen), aber Starts werden abgelehnt. Deine Admin-App kann die Installation dann verknüpfen, ohne dass jemand einen Schlüssel kopiert: sie fragt sqlly.app nach einem Link-Code, der Lizenzinhaber genehmigt ihn in seinem Browser, und die App empfängt einen Schlüssel, der nur für diese Installation erzeugt wurde, und übergibt ihn an die Bridge mit PUT /manage/license. Die Bridge prüft ihn, speichert ihn und nutzt ihn über Neustarts hinweg weiter. Jede verknüpfte Installation hat ihren eigenen Schlüssel, sodass der Inhaber einen einzelnen widerrufen kann, ohne die anderen anzutasten. Wie du es baust.

Wenn die Lizenz nicht gültig ist

In jedem Zustand außer ok und grace, die Bridge hält offene Sockets verbunden, beantwortet aber jedes Anfrage-Frame mit einem Fehler, der einen klaren Satz enthält („… konnte seine Lizenz bei sqlly.app seit 40 Minuten nicht bestätigen; bitte deinen Administrator, das zu prüfen.“). Der SQLly-Client zeigt diesen Satz in seiner Statuszeile und als Benachrichtigung an, damit die Nutzer wissen, warum. Neue Sitzungen bekommen denselben Satz zu hören und werden geschlossen (Code 4503), und Launch-Tokens werden abgelehnt mit 503 license_not_ok. In der 15-tägigen Kulanzfrist nach Ablauf eines Zeitraums funktioniert alles, aber jeder Nutzer sieht einen Countdown. Jeder Zustand, erklärt.

Was deinen Server verlässt

Wird beim Check-in an sqlly.app gesendetNirgendwohin gesendet
Lizenzschlüssel · Bridge-Instanz-ID · Bridge-Version · Hostname · angeforderte Domain · Nutzer-IDs mit Plätzen · Anzahl offener Sitzungen Abfragen · Ergebnisse · Datenbanknamen und Hosts · Zugangsdaten · Profile · alles, was deine Nutzer eingeben

Offline-Lizenzen senden überhaupt nichts. Der Browser kommuniziert nur mit deiner App und deiner Bridge.