SQLly mit einer Abfrage öffnen
SQLly direkt in einem Abfrage-Tab starten: das Skript, seine Verbindung und Datenbank, Parameterwerte und die Cursor-Position, gesendet mit dem Launch-Token für „In SQLly öffnen“-Buttons.
Ein Start-Token öffnet normalerweise eine leere Workbench. Füge ein open Feld hinzu, wenn Sie es erstellen, und SQLly öffnet stattdessen direkt in einem oder mehreren Abfrage-Tabs: das Skript geladen, der Tab mit dem richtigen Server und der richtigen Datenbank verbunden, Ihre Parameterwerte ausgefüllt, der Cursor an der Stelle, an der Sie ihn platziert haben. Das gibt Ihnen "In SQLly öffnen"-Schaltflächen überall, wo Ihre App SQL anzeigt: neben einem Bericht, bei einer fehlgeschlagenen Abfrage, in einem Prüfpfad.
Nichts läuft von selbst. Ein Start lädt nur Tabs. Die Person im Browser sieht sich jede Abfrage an und drückt Ausführen — nach derselben Regel wie bei SQLlys Desktop-Abfragelinks. Es gibt keinen Weg, dass ein Start SQL ausführt.
Ein Token mit Startkontext erstellen
Es ist dasselbe POST /manage/tokens Aufruf wie bei jedem Launch (Schritt 4 zum Bauen deiner eigenen App), mit einem zusätzlichen Feld:
curl -s -X POST -H "Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN" \
-H 'content-type: application/json' http://127.0.0.1:8445/manage/tokens -d '{
"user": "dana.analyst",
"profile": "analysts",
"open": {
"connection": "Shop",
"database": "sales",
"title": "Big orders",
"script": "SELECT *\nFROM orders\nWHERE total > @min_total AND placed_at >= @since",
"parameters": { "min_total": 500, "since": { "type": "date", "value": "2026-10-01" } },
"cursor": { "line": 3, "column": 7 }
}
}'
Die Antwort ist das übliche Token plus openTabsdie Anzahl der Tabs, die die Sitzung öffnen wird:
{ "token": "…", "expiresAt": "2026-10-18T15:12:11Z", "proxyUrl": "wss://portal.example.com/sqlly/proxy",
"user": "dana.analyst", "profile": "analysts", "seatsUsed": 3, "seats": 25, "openTabs": 1 }
Übergib das Token an die Seite genau wie bei einem normalen Start. Wenn der Nutzer die Seite öffnet, verbindet sich SQLly mit Shop und wechselt zu sales, und zeigt einen Tab namens „Große Bestellungen“ mit der geladenen Abfrage, der Parameterleiste mit 500 und 2026-10-01 und dem Cursor in der dritten Zeile.
Was ein Tab enthalten kann
open ist ein Objekt oder eine Liste von bis zu 8 Einträgen für mehrere Tabs. Der erste erhält den Fokus. Jedes Feld ist optional, aber ein Eintrag braucht mindestens ein Skript oder eine Verbindung.
| Feld | Typ | Bedeutung |
|---|---|---|
connection | Zeichenkette | Eine Verbindung im Profil des Tokens, entweder nach Namen (Groß-/Kleinschreibung beliebig) oder nach ihrer ID. Lass sie weg, wenn das Profil nur eine Verbindung hat. Bei mehreren Verbindungen und ohne Namensangabe öffnet sich der Tab ohne Verbindung. |
database | Zeichenkette | Die Datenbank, zu der statt der Standarddatenbank der Verbindung gewechselt wird. Höchstens 128 Zeichen. |
title | Zeichenkette | Der Titel des Tabs. Höchstens 120 Zeichen. Ohne ihn benennt SQLly den Tab wie gewohnt. |
script | Zeichenkette | Das zu ladende SQL, unverändert. Höchstens 256 KiB. Windows-Zeilenenden werden zusammengefaltet zu \n. |
parameters | object | Werte im Skript für die @name Parameter, höchstens 64. Siehe Parameter. |
cursor | { line, column } | Wohin der Cursor gesetzt wird, beides ab 1 gezählt, die Spalte in Zeichen. Die Position muss innerhalb des Skripts liegen (eine Spalte direkt hinter dem Zeilenende ist erlaubt). |
Parameter
SQLLY hat typisierte Abfrageparameter: eine -- sqlly param: @name <type> die Zeile deklariert einen, und eine Leiste über den Ergebnissen hält seinen Wert. Startparameter nutzen dieselbe Leiste, sodass deine Werte als sichtbare, bearbeitbare Eingaben erscheinen und die Anweisungen selbst genau so geladen werden, wie du sie gesendet hast.
- Namen verwenden
@name, auf jeder Engine. Schicke den Schlüssel mit oder ohne das@("min_total"und"@min_total"sind dasselbe). Ein Name ist ein Buchstabe oder_gefolgt von Buchstaben, Ziffern oder_, höchstens 64 Zeichen, und darf nur einmal erscheinen (beliebige Groß-/Kleinschreibung). Wenn deine App Parameter auf eine andere Weise schreibt ($name,:name,?), schreibe sie beim Erstellen des Skripts um zu@namewenn du das Skript erstellst. - Ein einfacher Wert nimmt seinen Typ aus JSON: eine ganze Zahl ist
int, jede andere Zahldecimal,true/falsebool, eine Zeichenkettetext, undnulllässt die Eingabe leer, damit du sie ausfüllen kannst. - Ein typisierter Wert ist
{ "type": "date", "value": "2026-10-01" }. Die Typen sindtext,int,decimal,bool,date,datetime,time,uuid,jsonundbinary. Sende JSON-Dokumente als Zeichenketten mit"type": "json". - Deklarationen werden automatisch hinzugefügt. Für jeden Parameter, den das Skript nicht deklariert, fügt SQLly eine
-- sqlly param:Zeile über dem Skript, und der Cursor wandert mit dem Skript nach unten. Ein Parameter, den das Skript bereits deklariert, behält Deklaration und Typ aus dem Skript und bekommt deinen Wert. - Wie Werte die Datenbank erreichen. Wenn du auf Ausführen klickst, prüft SQLly jeden Wert anhand seines Typs und ersetzt jeden
@nameaußerhalb von Zeichenketten und Kommentaren durch ein Literal ersetzt, das für diese Engine korrekt geschrieben ist, und sendet dann die Anweisung. Ein Wert, der nicht in seinen Typ passt, stoppt den Lauf und fokussiert das betreffende Eingabefeld. Deine App setzt niemals Werte direkt in den SQL-Text.
Ein Start, ein Token
- Die Tabs öffnen sich nur einmal. Die Bridge übergibt sie an die erste SQLly-Sitzung, die das Token benutzt, und vergisst sie dann. Beim Neuladen der Seite wird die Workbench wiederhergestellt, die SQLly im Browser sichert, sodass die Tabs nicht doppelt geöffnet werden. Das Token selbst funktioniert weiter, bis es abläuft.
- Ein frisches Token für jeden Klick auf „In SQLly öffnen“. Verwende kein zwischengespeichertes Token für einen Start mit Kontext: Es würde nichts öffnen. Ein neues Token für einen Nutzer, der bereits einen Platz belegt, kostet keinen zusätzlichen Platz.
- Jeder Klick ist ein neuer Tab. Es wird auf das Sitzungskontingent des Nutzers angerechnet
sessionsPerSeat(vier bei bezahlten Plänen, einer bei der Testversion). Bei der Testversion muss der Benutzer zuerst seinen anderen SQLly-Tab schließen, sonst wird der neue mit „<user> hat bereits die maximale Anzahl von geöffneten SQLly-Sitzungen“ abgelehnt. - Der Kontext wird beim Erstellen des Tokens festgelegt - wie beim Profil. Verbindungen werden gegen das Profil aufgelöst, so wie es dann gerade ist.
Fehler werden beim Ausstellen des Tokens erkannt
Die Bridge überprüft den gesamten open Wert, bevor sie das Token erstellt, sodass dein Server sofort Bescheid weiß, anstatt dass ein Nutzer erst einen defekten Tab findet. Ein schlechter Wert ist 400 invalid_open mit einem Eintrag in problems pro Fehler, wobei jeweils angegeben wird, wo er sich befindet. Es wird kein Token geprägt und kein Platz eingenommen:
{
"error": "invalid_open",
"message": "the launch context has 3 problems",
"problems": [
"open[0].connection: no connection \"Shopp\" in this profile (it has: Shop, Warehouse)",
"open[0]: unknown field \"sql\" (allowed: connection, database, title, script, parameters, cursor)",
"open[1].cursor: line 9 is past the end of the script (3 lines)"
]
}
Unbekannte Felder werden abgelehnt, anstatt ignoriert zu werden, sodass ein Tippfehler wie sql für script laut fehlschlägt. Werte des Typs int, decimal und bool werden ebenfalls geprüft. Andere Typen prüft SQLlys Parameterleiste, bevor eine Abfrage ausgeführt wird.
Rezepte
Eine Abfrage aus dem Audit-Trail erneut öffnen
das Abfrage-Audit-Trail zeichnet jede Abfrage mit Profil, Verbindung, Datenbank und SQL auf, was genau das ist, was ein Start braucht. Die Abfragen-Seite der Beispiel-App hat ein In SQLly erneut öffnen Schaltfläche bei jeder vollständigen Anweisung. Sie sucht die Zeile erneut auf der Bridge (das Formular benennt die Zeile und sonst nichts) und erstellt dann einen Admin-Start mit diesem Kontext:
javascriptconst entry = (await bridge('GET', '/manage/queries?limit=1000')).queries
.find((q) => String(q.sessionId) === form.session && q.id === form.id);
if (!entry || entry.kind === 'row-edit' || entry.sqlTruncated) return refuse();
const open = {
connection: entry.connection,
title: `${entry.status === 'failed' ? 'Failed' : 'Query'} from ${entry.user}`,
script: entry.sql,
};
if (entry.database) open.database = entry.database;
const minted = await bridge('POST', '/manage/tokens', { user: `admin:${admin.id}`, profile: entry.profile, open });
Das protokollierte SQL ist das, was tatsächlich ausgeführt wurde, deshalb sind die Parameterwerte darin bereits Literale und es werden keine Parameter benötigt. Bei einer fehlgeschlagenen Anweisung liest die Beispiel-App auch, wo die Engine den Fehler verortet (PostgreSQLs POSITION: 53, bei MySQL „at line 2“) und sendet dies als cursor, sodass der Cursor auf der problematischen Spalte landet.
„In SQLly öffnen“ auf der Fehlerseite deiner App
Wenn deine App eigenes SQL ausführt (ein Berichtsgenerator, ein SQL-gesteuertes Seiten-Framework, geplante Jobs), weiß sie im Moment des Fehlers, welche Anweisung es war, welche Werte daran gebunden waren und gegen welche Datenbank sie lief. Setz auf die Fehlerseite einen Button, der damit einen Start erzeugt: diese Anweisung, ihre Werte als Parameter, und der Cursor in der Zeile, über die sich die Datenbank beschwert hat. Der Entwickler bekommt eine komplette Arbeitsumgebung für diese Abfrage, mit IntelliSense, Objekt-Explorer und Ausführungsplänen, ganz ohne manuelles Kopieren:
javascript// failure = { sql: 'SELECT … WHERE id = $id', params: { id: 42 }, line: 3 }
const script = failure.sql.replace(/\$([A-Za-z_]\w*)/g, '@$1'); // $id → @id
const minted = await bridge('POST', '/manage/tokens', {
user: req.user.id,
profile: 'app-database', // a profile pointing at the app's own database
open: {
title: 'Failed statement',
script,
parameters: failure.params,
cursor: failure.line ? { line: failure.line, column: 1 } : undefined,
},
});
Biete das nur Personen an, die eine Arbeitsumgebung auf dieser Datenbank haben sollten, zum Beispiel in einer Entwicklungsumgebung oder für Administratoren. Das Profil entscheidet, worauf sie zugreifen können, genau wie bei jedem anderen Start.