API-Referenz
Jeder Endpunkt der Verwaltungs-API der SQLly-Embedded-Bridge, generiert aus ihrem OpenAPI-Dokument (swagger.json), plus die sqlly.app-Verknüpfungsendpunkte.
Die SQLly-Bridge im Embedded-Modus stellt diese API auf ihrem Management-Listener bereit (--manage-bind, Standard 127.0.0.1:8445). Deine Webanwendung ruft es serverseitig auf, um Verbindungsprofile zu speichern, Verbindungen zu testen, Start-Token für angemeldete Benutzer auszustellen, Sitze zu überwachen und den Lizenzstatus zu lesen oder zu ändern.
Jedes /manage/... Aufruf erfordert Authorization: Bearer <manage token> (der Brücke --manage-token, mindestens 16 Zeichen). Die Inhalte sind JSON in beide Richtungen, höchstens 8 MB (abgelehnt mit 413 too_large sobald das Limit überschritten ist). Pfadsegmente und Werte der Abfragezeichenfolge werden prozentdekodiert; eine ungültige Escape-Sequenz ist 400 bad_request. Fehler haben immer die Form { "error": "<code>", "message": "<sentence>" }, plus problems , wenn ein Dokument mit Anmeldeinformationen ungültig ist. Die API sendet keine CORS-Header: Halte sie auf dem Loopback oder in einem privaten Netzwerk und setze sie niemals Browsern aus, da Profile Datenbankpasswörter enthalten.
das Linking Operationen befinden sich nicht auf der Bridge: Sie sind die öffentlichen Endpunkte von sqlly.app, die eine Admin-App verwendet, um eine Installation mit einer Lizenz zu verknüpfen, ohne einen Schlüssel zu kopieren. Ihr Server ist sqlly.app.
Leitfaden: sqlly.app/docs/embedded
Konventionen
- Authentifizierung:
Authorization: Bearer <manage token>bei jedem/manage/…aufrufen. Ein fehlendes oder falsches Token ist401 unauthorized./healthzund die sqlly.app-Verknüpfungspunkte benötigen keines. - Fehler sind
{ "error": "<code>", "message": "<sentence>" }. Verzweige nacherror; anzeigenmessage. Ungültige Zugangsdaten-Dokumente liefernproblems, eine Zeichenkette pro Fehler. - Bodies sind JSON, maximal 8 MB. Das Limit wird durchgesetzt, während der Body ankommt: die Bridge antwortet
413 too_largein dem Moment, in dem er übergeben wird, und puffert nie mehr. Ein Body, für dessen Ankunft mehr als 30 Sekunden vergehen, wird408 timeout. Alles, was sich nicht parsen lässt, ist400 bad_json, und eine unbekannte Route ist404 not_found. - Pfadsegmente und Abfragewerte werden prozentdekodiert, also URL-codiere Benutzer-IDs und Zeitstempel (
DELETE /manage/seats/a%2Fbgibt den Benutzer wieder freia/b). Eine ungültige Escape-Sequenz oder ein Ergebnis, das nicht UTF-8 ist, ist400 bad_request. - Feldnamen sind camelCase in den eigenen Payloads der API. Innerhalb eines Credential-Dokuments folgen sie dem Credential-Format (
sql_auth_accounts,trust_server_certificate).
Endpunkte
- GET
/healthz - GET
/manage/status - POST
/manage/license/checkin - PUT
/manage/license - DELETE
/manage/license - GET
/manage/engines - GET
/manage/profiles - GET
/manage/profiles/{id} - PUT
/manage/profiles/{id} - DELETE
/manage/profiles/{id} - POST
/manage/tokens - GET
/manage/seats - DELETE
/manage/seats/{user} - POST
/manage/test-connection - GET
/manage/queries - POST
/api/embedded/links - POST
/api/embedded/links/token - GET
/api/embedded/public-key
Zustand
Liveness, kein Token nötig.
/healthz
kein Token
Liveness-Probe
Antwortet, sobald der Management-Listener aktiv ist. Benötigt kein Token; verwenden Sie es in Startskripten und Service-Health-Checks.
- 200
- Die Verwaltungs-API lauscht.
Beispielantwort 200
{
"ok": true
}
Lizenz
Die Lizenz, unter der die Bridge läuft: Status, Check-in, Verknüpfen und Trennen.
/manage/status
Status der Brücke und der Lizenz
Alles, was eine Admin-Ansicht benötigt: der Lizenzstatus und woher er stammt, die Kontingente, die die signierte Berechtigung enthält, belegte Plätze, offene Sitzungen und die Proxy-URL, die Browser verwenden.
- 200
- Aktueller Status.
- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
"version": "1.1.0",
"instanceId": "b5e1c0f2-7d3a-4c8e-9a61-0f2d4b7e9c13",
"mode": "connected",
"license": {
"state": "ok",
"source": "linked",
"licenseId": "emb_Q2x0b3VkU3FsbHkxMjM0NTY3",
"plan": "embedded-25",
"planName": "SQLly Embedded 25",
"status": "active",
"seats": 25,
"sessionsPerSeat": 4,
"instances": 1,
"domain": "portal.example.com",
"periodEnd": "2027-10-14T00:00:00+00:00",
"graceEnd": null,
"daysRemaining": 365,
"lastCheckinAt": "2026-10-14T15:00:02Z",
"staleAt": "2026-10-14T15:40:02Z",
"licenseFile": null,
"message": null,
"fromCache": false,
"features": [
"embedded",
"unlimited-connections",
"all-engines",
"test-connection"
]
},
"seatsUsed": 3,
"activeSessions": 4,
"proxyUrl": "wss://portal.example.com/sqlly/proxy",
"allowLocalhostOrigins": false,
"storeUrl": "https://sqlly.app",
"allowFileEngines": false
}
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license/checkin
Checke jetzt bei sqlly.app ein
Verbundene und verlinkte Lizenzen: führt eine Check-in-Prüfung sofort durch, anstatt auf die 20-minütige Schleife zu warten. Offline-Lizenzen: liest die Lizenzdatei erneut ein und greift niemals auf das Netzwerk zu. In jedem Fall ist die Antwort der Status nach dem Versuch; ein Fehlschlag lässt den Zustand unverändert.
- 200
- Status nach dem Check-in.
- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 409
not_linked: die Bridge ist nicht lizenziert, es gibt nichts zu melden.- 422
license_file_invalid(offline): die Datei fehlt, ist beschädigt oder für einen anderen Schlüssel signiert.- 502
store_unreachableodergrant_invalid: sqlly.app konnte nicht erreicht werden, oder ihre Antwort ließ sich nicht verifizieren.
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Beispielantwort 409
{
"error": "not_linked",
"message": "this bridge is not linked to a license yet"
}
/manage/license
Verknüpften Lizenzschlüssel installieren
Gibt eine Bridge, die ohne --license-key / --license-file seinen Schlüssel zur Laufzeit (normalerweise den Schlüssel, den deine Admin-App gerade über den Link-Flow von sqlly.app eingesammelt hat). Die Bridge meldet sich zuerst damit an und speichert ihn (<state-dir>/license-key, Modus 0600) nur, wenn sqlly.app mit einem verifizierten Grant antwortet; von da an läuft sie als verbundene Bridge, und der Schlüssel wird nach Neustarts wiederverwendet. Bei einem Fehler ändert sich nichts: Der verwendete Schlüssel dient weiter, bis der neue verifiziert ist. Das Ersetzen eines verknüpften Schlüssels durch einen einer anderen Lizenz gibt den Instanzplatz der alten Lizenz frei, sobald der neue Schlüssel verifiziert ist; ein neu erzeugter Schlüssel derselben Lizenz verwendet die Instanzzeile im Store wieder.
Anfragetext (LinkLicenseRequest)
{
"licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
- 200
- Verknüpft. Der Status zeigt jetzt
license.source: linked. - 400
invalid_license_key: leerer, fehlerhafter, unbekannter oder widerrufener Schlüssel.- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 409
license_from_flag: die Bridge wurde gestartet mit--license-keyoder--license-file, daher wird ihre Lizenz nicht über diese API verwaltet.- 502
store_unreachable: sqlly.app konnte nicht erreicht werden oder ihre Antwort ließ sich nicht verifizieren.
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license
Diese Installation trennen
Gibt den Instanz-Slot dieser Bridge frei, widerruft den Schlüssel auf sqlly.app (nach bestem Bemühen), löscht den gespeicherten Schlüssel, schließt alle offenen Sitzungen und setzt die Bridge zurück auf unlicensed.
- 204
- Getrennt.
- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 404
not_linked: kein verknüpfter Schlüssel gespeichert.- 409
license_from_flag: die Bridge wurde gestartet mit--license-keyoder--license-file, daher wird ihre Lizenz nicht über diese API verwaltet.
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Engines
Die Datenbank-Engines, die das Anmeldeinformationsformat akzeptiert, sodass deine UI die Liste nie fest codiert.
/manage/engines
Engines, die das Anmeldeinformationsformat akzeptiert
Jede Datenbank-Engine, die SQLly unterstützt, mit der engine ID zum Eintragen in ein Zugangsdaten-Dokument, ihr Standardport, ob server ein Dateipfad ist und die authentication.type Werte, die er akzeptiert.
- 200
- Die Engines.
- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
[
{
"id": "sql-server",
"name": "Microsoft SQL Server",
"defaultPort": 1433,
"fileBased": false,
"authentication": [
"sql-login",
"integrated",
"entra-browser",
"entra-device-code"
]
},
{
"id": "postgres",
"name": "PostgreSQL",
"defaultPort": 5432,
"fileBased": false,
"authentication": [
"sql-login"
]
},
{
"id": "sqlite",
"name": "SQLite",
"defaultPort": 0,
"fileBased": true,
"authentication": [
"none"
]
}
]
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Profile
Ein Profil ist ein benanntes SQLly-Anmeldeinformationsdokument: die Verbindungen (und Labels), die eine Benutzergruppe sieht. Die Bridge ist der maßgebliche Speicher; Geheimnisse erreichen nie den Browser.
/manage/profiles
Profile auflisten
Jedes gespeicherte Profil ohne seine Zugangsdaten.
- 200
- Die Profile.
- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
[
{
"id": "analysts",
"name": "Analysts",
"connections": 2,
"updatedAt": "2026-10-14T15:02:11Z"
}
]
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Ein Profil lesen
Das Profil mit seinem vollständigen Zugangsdaten-Dokument, Secrets eingeschlossen: Der Aufrufer ist deine vertrauenswürdige serverseitige App.
- id
- Pfad · Zeichenkette passend zu ^[A-Za-z0-9_-]{1,64}$ · erforderlich - deine ID für das Profil.
- 200
- Das Profil.
- 400
invalid_profile_id: IDs sind 1-64 vonA-Z a-z 0-9 _ -.- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 404
unknown_profile: kein Profil hat diese ID.
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Beispielantwort 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
Ein Profil erstellen oder ersetzen
Speichert das Profil unter id (erstellen oder ersetzen). Das Dokument mit den Anmeldeinformationen wird vollständig validiert, bevor irgendetwas geschrieben wird: Jedes Problem, das der Parser findet, wird in problems, und ein ungültiges Dokument ändert nichts. Ein Dokument mit einer dateibasierten Engine (SQLite, DuckDB) wird genauso abgelehnt, es sei denn, die Bridge läuft mit --allow-file-engines true, weil eine solche Verbindung ihren Benutzern Dateizugriff auf dem Bridge-Host gibt. Bereits geöffnete Sitzungen behalten den Katalog, mit dem sie gestartet sind; Änderungen greifen erst beim nächsten Start.
- id
- Pfad · Zeichenkette passend zu ^[A-Za-z0-9_-]{1,64}$ · erforderlich - deine ID für das Profil.
Anfragetext (PutProfileRequest)
{
"name": "Analysts",
"credentials": {
"format": "sqlly-credentials",
"version": 1,
"clients": [
{
"name": "Northwind Traders",
"color": "#1E88E5"
}
],
"environments": [
{
"name": "Production",
"color": "#C62828",
"safety": {
"only_allow_select": true
}
}
],
"sql_auth_accounts": [
{
"name": "Reader",
"username": "reader",
"password": "…"
}
],
"connections": [
{
"name": "Northwind",
"engine": "sql-server",
"server": "sql01.internal",
"database": "Northwind",
"environment": "production",
"client": "Northwind Traders",
"authentication": {
"type": "sql-login",
"account": "Reader"
},
"tls": {
"encrypt": true,
"trust_server_certificate": true
}
},
{
"name": "Warehouse",
"engine": "postgres",
"server": "dw.internal",
"database": "dw",
"environment": "production",
"client": "Northwind Traders",
"authentication": {
"type": "sql-login",
"account": "Reader"
},
"tls": {
"mode": "verify-full"
}
}
]
}
}
- 200
- Gespeichert.
- 400
invalid_profile(mitproblems: Parserprobleme oder jede dateibasierte Engine während--allow-file-enginesaus ist), oderinvalid_profile_id.- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 500
storage: in das Zustandsverzeichnis konnte nicht geschrieben werden.
Beispielantwort 400
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Ein Profil löschen
Entfernt das Profil. Offene Sitzungen behalten den Katalog, mit dem sie gestartet wurden; neue Start-Tokens dafür werden abgelehnt mit unknown_profile.
- id
- Pfad · Zeichenkette passend zu ^[A-Za-z0-9_-]{1,64}$ · erforderlich - deine ID für das Profil.
- 204
- Gelöscht.
- 400
invalid_profile_id: IDs sind 1-64 vonA-Z a-z 0-9 _ -.- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 404
unknown_profile: kein Profil hat diese ID.
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Beispielantwort 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
Starten
Launch-Tokens öffnen SQLly für einen Nutzer mit einem Profil. Plätze sind gleichzeitige Nutzer.
/manage/tokens
Ein Starttoken erstellen
Erstellt ein kurzlebiges Token, das SQLly öffnet für user mit profile, optional direkt in Abfragetabs (open, den Startkontext). Nimm das zurückgegebene proxyUrl und token auf die Seite, die SQLly lädt (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). Das Token lässt sich bis zum Ablauf (Seitenneuladen) wiederverwenden, und das Profil wird beim Ausstellen erfasst.
Ein Benutzer hält einen Platz, solange er eine offene Sitzung oder ein nicht abgelaufenes Token hat. Das Erstellen eines Tokens für einen Benutzer, der bereits einen Platz hält, schlägt in Bezug auf die Platzanzahl nie fehl; das Erstellen für einen neuen Benutzer schlägt fehl mit seat_limit wenn jeder Lizenzplatz belegt ist, wobei die Benutzer auf allen Bridges der Lizenz mitgezählt werden.
Anfragetext (MintTokenRequest)
{
"user": "dana.analyst",
"profile": "analysts",
"open": {
"connection": "Shop",
"database": "sales",
"title": "Big orders",
"script": "SELECT *\nFROM orders\nWHERE total > @min_total",
"parameters": {
"min_total": 500
},
"cursor": {
"line": 3,
"column": 7
}
}
}
- 201
- Das Token.
- 400
invalid_user(leer oder enthält Leerzeichen, höchstens 128 Zeichen),invalid_profile(das gespeicherte Profil ist nicht mehr gültig oder enthält eine dateibasierte Engine, während--allow-file-enginesaus ist), oderinvalid_open(der Startkontext eine unbekannte Verbindung, ein unbekanntes Feld oder einen unbekannten Typ, einen falschen Parameternamen oder -wert, einen Cursor außerhalb des zulässigen Bereichs nennt oder ein Limit übergibt;problemslistet jeden Fehler mit seinem Pfad auf, z. B.open[1].cursor: …).- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.- 404
unknown_profile: kein Profil hat diese ID.- 409
seat_limit: jeder Sitzplatz ist belegt. Gib einen frei (DELETE /manage/seats/{user}) oder einen größeren Tarif kaufen.- 503
license_not_ok: die Lizenz ist nichtokodergrace(veraltet, abgelaufen, widerrufen, nicht zugelassen, Domain-Abweichung oder nicht lizenziert). Die Nachricht gibt an, welche.
Beispielantwort 201
{
"token": "elt_q3J0n8w2Zx5rVb1kTq9yLs4dHf7cMa6p",
"expiresAt": "2026-10-14T15:12:11Z",
"proxyUrl": "wss://portal.example.com/sqlly/proxy",
"user": "dana.analyst",
"profile": "analysts",
"seatsUsed": 3,
"seats": 25,
"openTabs": 0
}
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats
Genutzte Lizenzplätze
Benutzer, die einen Platz an dieser Bridge belegen, mit ihren offenen Sitzungen und aktiven Tokens. seatsUsed Zählt auch Benutzer, die sqlly.app auf anderen Brücken derselben Lizenz gemeldet hat.
- 200
- Nutzung der Lizenzplätze.
- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
"seats": 25,
"seatsUsed": 2,
"users": [
{
"user": "dana.analyst",
"activeSessions": 1,
"tokens": 1,
"since": "2026-10-14T15:02:11Z"
},
{
"user": "sam.support",
"activeSessions": 2,
"tokens": 1,
"since": "2026-10-14T14:40:03Z"
}
]
}
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
Platz eines Benutzers freigeben
Entzieht die Token des Benutzers, schließt seine Sitzungen und gibt den Sitzplatz sofort frei. Ruf ihn auf, wenn sich ein Benutzer von deiner App abmeldet oder den Zugriff verliert. Das Freigeben eines Benutzers ohne Sitzplatz ist kein Fehler. Das Pfadsegment wird prozentdekodiert: a%2Fb gibt den Benutzer wieder frei a/b.
- Benutzer
- Pfad · Zeichenkette · erforderlich - Die Benutzer-ID, für die du Tokens ausgestellt hast (URL-codiert).
- 204
- Freigegeben.
- 400
bad_request: das Segment ist keine gültige Prozentkodierung.- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Verbindungen
Beweise, dass eine Verbindung funktioniert, bevor jemand sie benutzt.
/manage/test-connection
Eine Verbindung testen
Führt eine Wegwerf-Engine gegen ein Zugangsdaten-Dokument aus, das genau eine Verbindung enthält, und führt eine triviale Abfrage aus. Verbindungsfehler werden gemeldet als ok: false mit der eigenen Meldung der Engine (HTTP 200); nur ein unbrauchbares Dokument ist ein HTTP-Fehler.
Anfragetext (TestConnectionRequest)
{
"credentials": {
"format": "sqlly-credentials",
"version": 1,
"connections": [
{
"name": "Northwind",
"engine": "sql-server",
"server": "sql01.internal",
"database": "Northwind",
"authentication": {
"type": "sql-login",
"username": "reader",
"password": "…"
},
"tls": {
"encrypt": true,
"trust_server_certificate": true
}
}
]
}
}
- 200
- Das Ergebnis, ob erfolgreich oder nicht.
- 400
invalid_profile: das Dokument ist ungültig, hält nicht genau eine Verbindung oder verwendet eine dateibasierte Engine, während--allow-file-enginesausgeschaltet ist (sieheproblems).- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
"ok": true,
"elapsedMs": 212,
"message": "Connected: SQL Server 17.0"
}
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Audit
Das Abfrage-Audit-Protokoll: jede Abfrage und jede Zeilenbearbeitung, die eine Sitzung ausgeführt hat, wer sie ausgeführt hat, über welche Verbindung und wie sie endete. Gespeichert im Arbeitsspeicher und in <state-dir>/queries.jsonl (inklusive SQL-Text) aufbewahrt, es sei denn, die Bridge läuft mit --query-log false.
/manage/queries
Abfrage-Auditprotokoll
Jede Abfrage und Zeilenbearbeitung, die die Sitzungen der Bridge ausgeführt haben, neueste zuerst: der Benutzer und das Profil des Start-Tokens, die benannte Verbindung (Name, Server, Engine, Datenbank), der SQL-Text (auf 64 KiB gekürzt, siehe sqlTruncated), wann es gestartet wurde, seinen Status und seine Dauer sowie den Fehler der Engine, wenn sie fehlschlug. Anfragen, die noch ausgeführt werden, werden mit Status aufgelistet running; eine Anfrage, die abgelehnt wurde, weil die Lizenz nicht in Ordnung war, ist failed mit der Lizenznachricht; alles, was ausgeführt wurde, als eine Sitzung geschlossen wurde, ist cancelled mit Fehler session closed.
Die Bridge behält die neuesten --query-log-max-entries Einträge (standardmäßig 20.000) im Speicher und in <state-dir>/queries.jsonl, sodass die Spur einen Neustart überlebt. Mit --query-log false wird nichts aufgezeichnet und die Antwort ist { "enabled": false, "queries": [] }.
- Grenze
- Abfrage · Ganzzahl - Zurückzugebende Einträge, auf 1-1000 beschränkt.
- Benutzer
- Abfrage · Zeichenkette - Nur diese Benutzer-ID (exakte Übereinstimmung, URL-codiert).
- Profil
- Abfrage · Zeichenkette - Nur diese Profil-ID (exakte Übereinstimmung).
- seit
- Abfrage · Zeichenkette (Datum-Uhrzeit) - Nur Einträge, deren
atsich an oder nach diesem RFC 3339-Zeitstempel befindet (URL-codiert). - Status
- Abfrage · QueryStatus - Nur Einträge in diesem Status.
- 200
- Die passenden Einträge, neueste zuerst.
- 400
bad_request:limitist keine ganze Zahl,sinceist nicht RFC 3339,statusist unbekannt, oder ein Wert ist keine gültige Prozentkodierung.- 401
unauthorized: das Verwaltungstoken fehlt oder ist falsch.
Beispielantwort 200
{
"enabled": true,
"total": 2,
"limit": 200,
"queries": [
{
"id": "q-7",
"sessionId": 12,
"kind": "query",
"at": "2026-10-14T15:04:09.120Z",
"user": "dana.analyst",
"profile": "analysts",
"profileName": "Analysts",
"connection": "Northwind",
"server": "sql01.internal",
"database": "Northwind",
"engine": "Microsoft SQL Server",
"sql": "SELECT TOP 100 * FROM Orders",
"sqlTruncated": false,
"status": "completed",
"durationMs": 184,
"error": null
},
{
"id": "q-6",
"sessionId": 12,
"kind": "query",
"at": "2026-10-14T15:03:51.004Z",
"user": "dana.analyst",
"profile": "analysts",
"profileName": "Analysts",
"connection": "Northwind",
"server": "sql01.internal",
"database": "Northwind",
"engine": "Microsoft SQL Server",
"sql": "SELECT * FROM Ordres",
"sqlTruncated": false,
"status": "failed",
"durationMs": 31,
"error": "Invalid object name 'Ordres'."
}
]
}
Beispielantwort 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Verknüpfung
sqlly.app-Endpunkte (Server sqlly.app) zum Verknüpfen einer Installation mit einer Lizenz: du erstellst einen Code, der Besitzer genehmigt ihn in seinem Browser, du sammelst den eigenen Schlüssel der Installation einmalig und übergibst ihn dann mit PUT /manage/license an die Bridge.
/api/embedded/links
sqlly.app
kein Token
Verknüpfung einer Installation starten (sqlly.app)
Anonym. Erstellt eine Verknüpfungsanfrage und gibt einen kurzen Code zurück, ein Geheimnis, das nur deine App kennt, und die URL, unter der der Lizenzinhaber sie genehmigt. Zeig den Code und öffne linkUrl für den Besitzer, dann abfragen POST /api/embedded/links/token jede pollIntervalSeconds bis er genehmigt ist. Verknüpfungen verfallen nach 15 Minuten.
Anfragetext (CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- Verknüpfung erstellt.
- 429
- Rate limit erreicht.
- 503
link_unavailable: kein Code konnte zugewiesen werden; versuche es erneut.
Beispielantwort 201
{
"linkId": "eml_Y2h9u0bQ1sXk4tWm8pZr3vLa",
"code": "K7Q-4MX",
"secret": "pW0r7…",
"linkUrl": "https://sqlly.app/embedded/link?code=K7Q-4MX",
"expiresAt": "2026-10-14T15:17:11Z",
"pollIntervalSeconds": 3
}
/api/embedded/links/token
sqlly.app
kein Token
Nach dem verknüpften Schlüssel abfragen (sqlly.app)
Anonym; das Link-Geheimnis ist die Anmeldeinformation. Solange der Eigentümer nicht entschieden hat, antwortet 202 pending. Nach der Freigabe wird der eigene Lizenzschlüssel dieser Installation erzeugt und genau einmal zurückgegeben (der Link wird verbraucht). Übergib den Schlüssel direkt an die Bridge mit PUT /manage/license; speichere ihn nicht selbst.
Anfragetext (LinkTokenRequest)
- 200
- Genehmigt: der Schlüssel, einmal.
- 202
- Wartet noch auf den Eigentümer.
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expiredoderlicense_revoked: dieser Link kann nie abgeschlossen werden. Starte einen neuen.- 429
- Rate limit erreicht.
/api/embedded/public-key
sqlly.app
kein Token
Öffentlicher Schlüssel für Lizenzsignatur (sqlly.app)
Der öffentliche PEM-Schlüssel, mit dem sqlly.app Lizenzerteilungen signiert, damit ein Betreiber ihn mit dem in die Bridge einkompilierten Schlüssel vergleichen kann.
- 200
- PEM-Text.
- 503
signing_not_configured.
Schemas
Die obigen Objekte, wie definiert in swagger.json. Eine ? nach einem Typ bedeutet, dass er sein kann null.
Fehler
Jede Fehlermeldung. error ist ein stabiler Maschinencode; message ist ein Satz, den du einem Administrator zeigen kannst.
| Feld | Typ | Beschreibung |
|---|---|---|
error * |
string |
|
message * |
string |
|
problems |
string[] |
Vorhanden für invalid_profile: jedes Problem, das der Credential-Parser gefunden hat. |
LicenseState
ok und grace bedienen Abfragen; jeder andere Zustand lehnt die Arbeit mit einer Meldung ab, wie SQLly sie auch seinen Benutzern zeigt.
Eines von: ok grace stale not_admitted expired revoked domain_mismatch unlicensed
Statusbericht
| Feld | Typ | Beschreibung |
|---|---|---|
version |
string |
Bridge-Version. |
instanceId |
string |
Die ID dieses Bridge-Prozesses, wie sqlly.app sie sieht. |
mode |
connected | offline |
|
license |
LicenseReport |
|
seatsUsed |
integer |
Genutzte Lizenzplätze in allen Bridges der Lizenz. |
activeSessions |
integer |
Offene SQLly-Sitzungen auf dieser Bridge. |
proxyUrl |
string |
Die WebSocket-URL, die Browser verwenden (--public-url). |
allowLocalhostOrigins |
boolean |
|
storeUrl |
string |
|
allowFileEngines |
boolean |
Ob Profile dateibasierte Engines enthalten dürfen (--allow-file-engines). |
LicenseReport
Kontingente stammen aus dem signierten Grant, niemals aus unsignierten Daten.
| Feld | Typ | Beschreibung |
|---|---|---|
state |
LicenseState |
|
source |
flag | file | linked | none |
flag: --license-key; file: --license-file; linked: gespeichert durch PUT /manage/license; none: nicht lizenziert. |
licenseId |
string? |
|
plan |
string? |
Plan-ID, oder custom für eine Lizenz mit eigenen Bedingungen. |
planName |
string? |
|
status |
string? |
Status von sqlly.app beim letzten Check-in: active, grace, expired, revoked, domain_mismatch. |
seats |
integer |
Gleichzeitige Benutzer laut Lizenz. |
sessionsPerSeat |
integer |
Offene SQLly-Tabs, die ein Benutzer halten darf. |
instances |
integer |
Bridges, die gleichzeitig laufen dürfen (verbundene Lizenzen; 0 offline). |
domain |
string? |
Die gebundene Domain; Browser müssen von dieser oder einer Subdomain stammen. |
periodEnd |
string? |
Ende des bezahlten Zeitraums (ISO 8601). |
graceEnd |
string? |
Festgelegt während der Kulanz: wann die Bridge den Dienst einstellt. |
daysRemaining |
integer? |
Ganze Tage bis die Bridge den Dienst einstellt. |
lastCheckinAt |
string (date-time)? |
|
staleAt |
string (date-time)? |
Wann die Bridge als veraltet gilt: wenn kein Check-in erfolgreich war (letzte gültige Erteilung + 40 Minuten). |
licenseFile |
string? |
Offline: die verwendete Lizenzdatei. |
message |
string? |
Der Satz, den Nutzer sehen, wenn etwas nicht stimmt (auch Countdowns für die Gnadenfrist). |
fromCache |
boolean |
Wahr, wenn die Bridge von ihrem zwischengespeicherten Grant gestartet wurde, weil sqlly.app nicht erreichbar war. |
features |
string[] |
LinkLicenseRequest
| Feld | Typ | Beschreibung |
|---|---|---|
licenseKey * |
string |
Ein Schlüssel, der mit sqe_. |
EngineInfo
| Feld | Typ | Beschreibung |
|---|---|---|
id |
string |
das engine Wert für ein Dokument mit Anmeldeinformationen. |
name |
string |
|
defaultPort |
integer |
|
fileBased |
boolean |
server ist ein Dateipfad und keine Anmeldung wird benötigt. |
authentication |
string[] |
Akzeptiert authentication.type Werte. |
ProfileSummary
| Feld | Typ | Beschreibung |
|---|---|---|
id |
string |
|
name |
string |
|
connections |
integer |
Anzahl der Verbindungen im Dokument. |
updatedAt |
string (date-time) |
StoredProfile
| Feld | Typ | Beschreibung |
|---|---|---|
id |
string |
|
name |
string |
|
credentials |
CredentialDocument |
|
updatedAt |
string (date-time) |
PutProfileRequest
| Feld | Typ | Beschreibung |
|---|---|---|
name * |
string |
Anzeigename, der Benutzern in SQLly angezeigt wird. |
credentials * |
CredentialDocument |
CredentialDocument
Ein SQLly-Credentials-Dokument (im selben Format wie SQLlys Datei → Verbindungen importieren). Unbekannte Schlüssel sind Fehler, deshalb werden Tippfehler gemeldet statt ignoriert. Vollständige Referenz: sqlly.app/docs (Format der Anmeldeinformationsdatei).
| Feld | Typ | Beschreibung |
|---|---|---|
format * |
sqlly-credentials |
|
version * |
1 |
|
clients |
Label[] |
|
projects |
Label[] |
|
environments |
Label[] |
|
sql_auth_accounts |
SharedLogin[] |
|
tunnel_profiles |
object[] |
|
connections |
Connection[] |
Bezeichnung
| Feld | Typ | Beschreibung |
|---|---|---|
name * |
string |
|
color |
string |
#RGB, #RRGGBB oder #RRGGBBAA. |
image |
string |
Symbol als Daten-URI oder reines Base64 (PNG, JPEG, GIF, WebP, BMP, ICO, SVG; bis zu 1 MB). |
safety |
object |
Nur die aufgelisteten Flags ändern sich. |
SharedLogin
| Feld | Typ | Beschreibung |
|---|---|---|
name * |
string |
|
username * |
string |
|
password |
string |
Verbindung
| Feld | Typ | Beschreibung |
|---|---|---|
name * |
string |
|
engine * |
string |
Eine ID von GET /manage/engines. |
server * |
string |
Host, IP, host\instance oder ein Dateipfad für SQLite/DuckDB. |
port |
integer |
|
database |
string |
|
environment |
string |
local, dev, test, staging, production oder unset. |
client |
string |
Ein Client-Label-Name. |
project |
string |
Ein Projekt-Labelname. |
authentication |
Authentication |
|
tls |
object |
|
timeout_seconds |
integer |
|
statement_timeout_seconds |
integer |
|
application_name |
string |
|
safety |
object |
|
favorite |
boolean |
|
startup_sql |
string |
|
tunnel_profile |
string |
|
transport |
object |
Inline-Proxy, SSH- und Kube-Hops. |
masking |
object |
{ include: [...], exclude: [...] } Spalten-Masking-Regeln. |
Authentifizierung
| Feld | Typ | Beschreibung |
|---|---|---|
type * |
sql-login | integrated | entra-browser | entra-device-code | aws-rds-iam | gcp-cloud-sql-iam | auth-token | none |
|
username |
string |
|
password |
string |
|
account |
string |
Name eines gemeinsamen Logins in sql_auth_accounts. |
region |
string |
|
profile |
string |
|
token |
string |
MintTokenRequest
| Feld | Typ | Beschreibung |
|---|---|---|
user * |
string |
Deine stabile ID für den Benutzer (keine Leerzeichen). Lizenzplätze werden pro eindeutigem Benutzer gezählt. |
profile * |
string |
Eine Profil-ID. |
ttlSeconds |
integer |
Token-Lebensdauer; Standard ist --token-ttl-seconds (600) und ist auf 10 s - 24 h begrenzt. |
open |
LaunchTab | LaunchTab[] |
Startkontext: ein Abfrage-Tab oder bis zu 8, die SQLly beim Sitzungsstart öffnet. Die erste Sitzung, die der Token durchlässt, bekommt sie; Neuladen und spätere Sitzungen nicht. Beim Ausstellen gegen das Profil geprüft (400 invalid_open). Nichts läuft, bis der Benutzer auf „Ausführen“ drückt. Anleitung: sqlly.app/docs/embedded/launch-context |
LaunchTab
Ein Abfrage-Tab pro Start. Benötigt ein script, ein connection, oder beides.
| Feld | Typ | Beschreibung |
|---|---|---|
connection |
string |
Eine Verbindung im Profil des Tokens, nach Name (Groß-/Kleinschreibung wird ignoriert, muss eindeutig sein) oder ID. Optional, wenn das Profil nur eine Verbindung hat; bei mehreren Verbindungen und ohne Namensangabe öffnet sich der Tab ohne Verbindung. |
database |
string |
Datenbank, zu der gewechselt werden soll, anstelle der Standarddatenbank der Verbindung. |
title |
string |
Der Tab-Titel. |
script |
string |
Das SQL, das geladen werden soll, unverändert (maximal 256 KiB; CRLF wird zu LF zusammengeführt). |
parameters |
object |
Werte im Skript für die @name Parameter, nach Name geschlüsselt (mit oder ohne @). Der Typ eines einfachen Wertes wird abgeleitet (ganze Zahl int, andere Zahl decimal, Boolean bool, Zeichenfolge text, null leer); verwende { type, value } um auszuwählen. Parameter, die das Skript nicht deklariert, erhalten eine -- sqlly param: Zeile; die Werte erscheinen in SQLlys Parameterleiste und werden nie von deiner App eingefügt. |
cursor |
LaunchCursor |
LaunchParameterValue
| Feld | Typ | Beschreibung |
|---|---|---|
type |
text | int | decimal | bool | date | datetime | time | uuid | json | binary |
|
value |
string | number | boolean |
LaunchCursor
Caret-Position in script, 1-basiert; die Spalte zählt Zeichen und kann eine Stelle hinter dem Zeilenende liegen.
| Feld | Typ | Beschreibung |
|---|---|---|
line |
integer |
|
column |
integer |
MintedToken
| Feld | Typ | Beschreibung |
|---|---|---|
token |
string |
|
expiresAt |
string (date-time) |
|
proxyUrl |
string |
|
user |
string |
|
profile |
string |
|
seatsUsed |
integer |
Genutzte Lizenzplätze einschließlich dieses Benutzers. |
seats |
integer |
|
openTabs |
integer |
Wie viele Tabs die Sitzung öffnet (0 ohne Startkontext). |
SeatsReport
| Feld | Typ | Beschreibung |
|---|---|---|
seats |
integer |
|
seatsUsed |
integer |
|
users |
UserSeat[] |
UserSeat
| Feld | Typ | Beschreibung |
|---|---|---|
user |
string |
|
activeSessions |
integer |
|
tokens |
integer |
Nicht abgelaufene Start-Token. |
since |
string (date-time) |
TestConnectionRequest
| Feld | Typ | Beschreibung |
|---|---|---|
credentials * |
CredentialDocument |
TestOutcome
| Feld | Typ | Beschreibung |
|---|---|---|
ok |
boolean |
|
elapsedMs |
integer |
|
message |
string |
Die eigene Meldung der Engine, Erfolg oder Fehlschlag. |
QueryStatus
running bis die Engine antwortet; dann completed, failed (siehe error) oder cancelled (vom Benutzer, oder session closed).
Eines von: running completed failed cancelled
QueryEntry
Eine geprüfte Anfrage.
| Feld | Typ | Beschreibung |
|---|---|---|
id |
string |
Die Anfrage-ID der Engine, eindeutig innerhalb ihrer Sitzung. |
sessionId |
integer |
Die Bridge-ID für die Browsersitzung. |
kind |
query | row-edit |
|
at |
string (date-time) |
Wann die Anfrage die Bridge erreichte. |
user |
string |
Die Benutzer-ID des Start-Tokens. |
profile |
string |
Die Profil-ID des Start-Tokens. |
profileName |
string |
|
connection |
string |
Der Name der Verbindung im Profil. |
server |
string |
|
database |
string? |
Die Datenbank des Profils, wenn es eine festlegt, sonst die in der Anfrage genannte Datenbank. |
engine |
string |
Der Anzeigename der Engine. |
sql |
string |
Der SQL-Text, oder row edit: <op> für eine Zeilenbearbeitung. Auf 64 KiB gekürzt. |
sqlTruncated |
boolean |
|
status |
QueryStatus |
|
durationMs |
integer? |
Null während der Ausführung. |
error |
string? |
Der Fehler der Engine für failed; session closed für eine Anfrage, die abgebrochen wurde, weil ihre Sitzung endete. |
QueryListing
| Feld | Typ | Beschreibung |
|---|---|---|
enabled |
boolean |
Falsch, wenn die Bridge mit --query-log false; dann queries immer leer. |
queries |
QueryEntry[] |
Neueste zuerst. |
total |
integer |
Einträge, die den Filtern entsprechen, vor limit angewendet wurde. |
limit |
integer |
Die angewendete Seitengröße (1-1000). |
CreateLinkRequest
| Feld | Typ | Beschreibung |
|---|---|---|
name |
string |
Wird dem Eigentümer auf der Genehmigungsseite und auf seiner Embedded-Seite angezeigt. |
hostname |
string |
|
appVersion |
string |
CreateLinkResponse
| Feld | Typ | Beschreibung |
|---|---|---|
linkId |
string |
|
code |
string |
Zeig das dem Eigentümer, damit er prüfen kann, ob es übereinstimmt. |
secret |
string |
Serverseitig behalten; dort wird der Schlüssel erfasst. |
linkUrl |
string |
Öffne das, damit der Besitzer es freigeben kann. |
expiresAt |
string (date-time) |
|
pollIntervalSeconds |
integer |
LinkTokenRequest
| Feld | Typ | Beschreibung |
|---|---|---|
linkId * |
string |
|
secret * |
string |
LinkPending
| Feld | Typ | Beschreibung |
|---|---|---|
status |
pending |
|
expiresAt |
string (date-time) |
LinkApproved
| Feld | Typ | Beschreibung |
|---|---|---|
status |
approved |
|
licenseKey |
string |
Einmal genau zurückgegeben. An PUT /manage/license weitergeben. |
keyId |
string |
|
licenseId |
string |
|
plan |
string |
Plan-ID, oder custom. |
planName |
string |
|
accountEmail |
string |
* erforderlich