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
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-cliProzess, 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:
| Job | Lauscht auf | spricht 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 /proxy | Browser (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:8445 | Nur 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. | Nichts | sqlly.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
- Ein angemeldeter Benutzer öffnet die SQLly-Seite in deiner App.
- Dein Server kontaktiert
POST /manage/tokensmit 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). - 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.
- Dein Server liefert die SQLly-Seite zurück (
web/index.html) mit zwei vorher gesetzten globalen Variablenboot.js:SQLLY_PROXY_URLundSQLLY_PROXY_TOKEN. - SQLly öffnet
wss://…/proxy?token=…. Die Bridge überprüft in folgender Reihenfolge: den BrowserOrigin(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 alserrorNachricht mit dem Grund geliefert, gefolgt vom Schließcode4000 + HTTP status(4401 unbekanntes oder abgelaufenes Token, 4503 Lizenz nicht in Ordnung, 4429 Sitzungslimit); SQLly zeigt den Satz an. - Die Bridge schreibt die Zugangsdaten des Profils in eine private pro Sitzung angelegte Datei und startet
sqlly-clidamit im Engine-Modus. - 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.
- 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
sessionsPerSeatgeö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/checkinmit 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 gesendet | Nirgendwohin 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.