Neu: Jede Funktion mit Schritt-für-Schritt-Anleitung und Screenshots.
Erweitern

Community Extensions

Extensions aus dem Extension-Markt oder als Paket installieren, Berechtigungen freigeben und eigene Extensions mit SDK und CLI bauen.

Community Extensions erweitern die App um Befehle, Seitenleisten-Ansichten, Statusleisten-Einträge und Knöpfe im Ausführungsplan. Sie laufen isoliert in einer Sandbox und dürfen nur, was ihnen ausdrücklich freigegeben wurde.

Datenbank-Extensions von PostgreSQL (CREATE EXTENSION) sind etwas anderes, siehe PostgreSQL-Extensions.

Öffnen

Einstellungen (Mod+,) > Erweiterungen („Community Plugins“). Die Seite hat zwei Abschnitte: Extension-Markt und Community Extensions. Siehe auch Einstellungen.

Extension-Markt

Extension-Markt

Offiziell unterstützte Extensions aus dem öffentlichen l8db-Katalog auf GitHub.

  • Jede Karte zeigt Name, Badge Offiziell, Version (v1.2.3), Beschreibung und ID.
  • Installieren lädt das Paket; danach steht dort Installiert. Bietet der Katalog eine neuere Version an, erscheint Aktualisieren.
  • Nach der Installation: {Name} installiert. Berechtigungen unten prüfen und aktivieren.
  • Aktualisieren oben lädt den Katalog neu. Zustände: Katalog wird geladen…, Katalog nicht verfügbar: …, Der Katalog enthält noch keine Extensions.

Prüfungen beim Installieren aus dem Markt:

  • Katalog und Paket nur über HTTPS, ohne Weiterleitungen; das Paket muss im Verzeichnis des Katalogs liegen.
  • Der SHA-256-Hash des Pakets muss zum Katalog passen, sonst Paket-Hash stimmt nicht mit dem Katalog überein.
  • ID, Version und Herausgeber im Paket müssen zum Katalog passen, sonst Paket-Metadaten stimmen nicht mit dem Katalog überein.
  • Grenzen: Katalog höchstens 256 KiB und 100 Einträge, Paket höchstens 8 MiB; Zeitlimit 10 s für den Katalog, 15 s für ein Paket.

Nach neuen Versionen sucht l8db nicht von selbst; der Knopf Aktualisieren erscheint nur, wenn der geladene Katalog eine neuere Version nennt.

Installieren und verwalten

Extensions - Übersicht

Im Abschnitt Community Extensions:

  • Paket installieren öffnet eine Datei mit der Endung .l8db-extension.
  • Entwicklungsordner laden lädt eine Extension direkt aus einem Projektordner, siehe Entwickeln.
  • Leer: Keine Community Extensions installiert.
  • Extension-Logs (N) klappt die Protokollzeilen aller Extensions auf (zeit [extension:id] stufe: meldung), höchstens 300.

Extension-Protokoll

Eine Extension mit derselben ID lässt sich nicht erneut installieren, sie muss vorher deinstalliert werden.

Community Extensions - Leer

Pakete sind nicht signiert, Herausgeber werden nicht verifiziert. Die einzige Prüfung ist der SHA-256-Abgleich bei Installationen aus dem Markt. Herausgeber und Berechtigungen vor dem Aktivieren prüfen.

Extension-Karte

Extension-Details

Kopf: Name, Version · Zustand · Aktiviert/Deaktiviert, ID und Beschreibung; Fehler erscheinen rot. Darunter je nach Manifest Entwicklung: {Pfad}, Ansichten: …, Panels: …, Statusleiste: …, Netzwerk-Hosts: … und Prozesse: ….

KnopfWirkung
Aktivierenspeichert die angehakten Berechtigungen und startet die Extension
Freigaben anwendenwie Aktivieren, bei bereits aktivierter Extension
Deaktivierenstoppt die Extension
Neu ladenstartet die Extension neu; bei Entwicklungsordnern wird der Ordner neu eingelesen
Aktualisiereninstalliert eine neuere Version aus einer .l8db-extension-Datei (nicht bei Entwicklungsordnern)
Deinstallierenentfernt Paket, eigenen Speicher und alle Geheimnisse der Extension im Schlüsselbund
Befehlsknöpfeein Knopf je Befehl der Extension; nur bei aktivierter Extension

Extension deinstallieren

Konfiguration (aufklappbar) listet die Einstellungen der Extension als Schlüssel (Typ) mit Beschreibung und Standard: …. Geändert wird über ein JSON-Feld und Speichern.

Lebenszyklus

  • Installieren: Die Extension ist deaktiviert und hat keine Berechtigungen.
  • Aktivieren: Ist onStartup angegeben, startet sie sofort; mit onDatabaseOpen, sobald eine Datenbank aktiv ist; sonst beim ersten Befehl oder beim Anzeigen ihrer Ansicht.
  • Aktualisieren: Die neue Version muss höher sein (Version X is not newer than Y). Speicher, Freigaben und Konfiguration bleiben erhalten. Was das neue Manifest nicht mehr nennt, entfällt. Neue Berechtigungen werden nicht automatisch freigegeben.
  • Neu laden bei Entwicklungsordnern: Hat sich das Manifest geändert, verlangt l8db eine Neuinstallation (Manifest changed: reinstall to review permissions and contributions).

Berechtigungen

Extension-Berechtigungen

Die Karte zeigt unter Berechtigungen ein Kästchen je Berechtigung, die das Manifest anfordert. Freigegeben wird erst mit Aktivieren bzw. Freigaben anwenden. Jeder Aufruf der Extension wird gegen die Freigaben geprüft.

BerechtigungErlaubt
database:readaktive Datenbank abfragen, lesende SQL-Abfragen, Datenbank-Ereignisse
database:writeschreibende SQL-Abfragen
networkHTTPS-Anfragen an die im Manifest genannten Hosts
filesystem:extension-storageeigener JSON-Speicher und Geheimnisse im Schlüsselbund
filesystemTextdateien lesen und schreiben, die der Benutzer im Datei-Dialog gewählt hat
clipboard:readZwischenablage lesen
clipboard:writeZwischenablage schreiben
process:executeim Manifest genannte Programme starten

In der aktuellen App lassen sich nur database:read, network und filesystem:extension-storage tatsächlich freigeben. Das Anhaken von database:write, filesystem, clipboard:read, clipboard:write oder process:execute scheitert beim Aktivieren mit Unsupported or undeclared permission. Extensions, die diese Berechtigungen anfordern, lassen sich nur ohne sie aktivieren.

Eine SQL-Abfrage gilt nur als lesend, wenn sie aus einer Anweisung besteht und mit SELECT, WITH, EXPLAIN, SHOW, DESCRIBE, DESC, VALUES oder TABLE beginnt. Bei Verbindungen im Lesemodus scheitern Schreibzugriffe mit Read-only connection.

Ohne Berechtigung nutzbar: Befehle, Benachrichtigungen, Dialoge, Ansichten, Statusleiste, Panels, Konfiguration, Logger und das Lesen eigener Dateien aus dem Paket.

Wo Extensions erscheinen

Extension-Aktionen im Kontextmenü

Extension-Befehle in der Befehlspalette

Extension-Ansichten in der Seitenleiste

Extension-Einträge in der Statusleiste

BeitragOrt in der App
BefehleBefehlspalette, Gruppe Extensions (wenn der Befehl ein Menü palette oder gar keinen Menüeintrag hat) und als Knopf auf der Extension-Karte
Ansichten mit location: "sidebar"eigene Gruppe in der Seitenleiste unter dem Objektbaum; leer: Keine Einträge.
Menü view/titleKnopf neben dem Titel der Ansicht
Menü view/itemKnopf beim Überfahren eines Eintrags der Ansicht; der Befehl erhält {viewId, itemId}
Menü explain/toolbarKnopf im Kopf des Ausführungsplans
Statusleisten-Einträgelinks oder rechts in der Statusleiste, nach Priorität sortiert; ein Klick führt den hinterlegten Befehl aus

Ein Befehl in explain/toolbar bekommt eine Zusammenfassung des Plans: höchstens 24 Knoten mit grob eingeteilten Werten für Art, Größe und Zeit, ohne SQL und ohne Namen.

Einige Beiträge werden angenommen, aber noch nicht angezeigt: Ansichten mit location: "panel", Menüeinträge mit location: "statusBar" und Panels. panels.open() merkt sich das Panel nur; die App öffnet dafür keinen Tab und bietet auch keinen Weg dorthin.

Offizielles Beispiel: Jev

Die einzige Extension im Markt ist derzeit l8db.jev (1.0.0). Sie fordert network (Host api.typesafe.ai) und filesystem:extension-storage an und bringt drei Befehle mit:

  • Mit Jev prüfen im Kopf des Ausführungsplans. Vor dem Senden zeigt sie die vollständige Anfrage mit dem Knopf An TypeSafe senden.
  • Jev: API-Schlüssel einrichten und Jev: API-Schlüssel löschen in der Befehlspalette. Der Schlüssel liegt im Schlüsselbund.

Entwickeln

Eine Extension ist ein Ordner mit Manifest l8db-extension.json, Quelltext src/extension.ts und optional einem Ordner assets/. Die Pakete @l8db/extension-api (Typen) und @l8db/extension-sdk (CLI) liegen im Repository unter packages/, das Beispiel examples/hello-extension zeigt Befehle, Ereignisse, eine Ansicht, Statusleiste und Konfiguration.

CLI

Im Repository:

bun run extension build examples/hello-extension
bun run extension validate examples/hello-extension
bun run extension pack examples/hello-extension
bun run extension dev examples/hello-extension

Allgemein: l8db-extension <build|validate|pack|dev> [ordner] [ausgabe.l8db-extension]. Ohne Ordner gilt das aktuelle Verzeichnis. Weitere Optionen oder einen Befehl zum Anlegen eines Projekts gibt es nicht.

BefehlWirkung
buildbündelt src/extension.ts mit Bun (Browser, CommonJS, eine Datei) nach main und meldet Built id@version
validateprüft Manifest und Paketinhalt, ohne vorher zu bauen, und meldet Valid: id@version
packbaut und schreibt <id>-<version>.l8db-extension oder die angegebene Ausgabedatei
devbaut, prüft und nennt den Ordner, der in l8db über Entwicklungsordner laden geladen wird

dev beobachtet keine Dateien. Nach Änderungen erneut bauen und auf der Karte Neu laden drücken.

Ein Paket enthält main und assets/: höchstens 256 Dateien, 8 MiB, nur UTF-8-Text, keine symbolischen Links.

Manifest

{
  "id": "community.hello",
  "name": "Hello l8db",
  "version": "1.0.0",
  "description": "A minimal community extension.",
  "publisher": "community",
  "engines": { "l8db": ">=0.1.0 <1.0.0", "api": "^1.0.0" },
  "main": "./dist/extension.js",
  "activationEvents": ["onCommand:hello.greet", "onDatabaseOpen", "onView:hello.overview"],
  "permissions": ["database:read"],
  "contributes": {
    "commands": [{ "id": "hello.greet", "title": "Hello: Greet" }],
    "views": [{ "id": "hello.overview", "title": "Hello Overview", "location": "sidebar" }],
    "statusBar": [{ "id": "hello.status", "alignment": "right", "priority": 10 }],
    "menus": [{ "command": "hello.greet", "location": "view/title", "view": "hello.overview" }],
    "configuration": {
      "hello.enabled": { "type": "boolean", "default": true, "description": "Show greeting notifications" }
    }
  }
}
FeldPflichtRegeln
idjapublisher.name aus Kleinbuchstaben, Ziffern und -, beginnt mit {publisher}., höchstens 160 Zeichen
name, publisherjanicht leer
versionjagültige SemVer-Version
engines.l8dbjaSemVer-Bereich, gegen die App-Version geprüft
engines.apinein^1.0.0 (Standard) oder ^1.1.0
mainjarelativer Pfad auf eine .js-Datei im Paket
activationEventsjaonStartup, onDatabaseOpen, onCommand:<id>, onView:<id>; höchstens 100
descriptionneinBeschreibung
permissionsneinsiehe Berechtigungen
dependenciesnein{ "pub.name": "<SemVer-Bereich>" }, nicht auf sich selbst
capabilities.network.hostsneinerlaubte Hosts, höchstens 50; *. als Präfix und :port erlaubt
capabilities.process.commandsneinerlaubte Programmnamen ohne Pfad, höchstens 50
contributesneinnur commands, configuration, views, panels, statusBar, menus

onCommand: und onView: müssen auf einen eigenen Befehl bzw. eine eigene Ansicht zeigen.

BeitragHöchstzahlFelder
commands100id, title, icon
configuration100Objekt aus Schlüssel und { type: boolean | string | number, default, description, enum }; enum 1–50 Werte
views20id, title, location (sidebar oder panel), icon
panels20id, title
statusBar20id, alignment (left oder right, Standard right), priority (Standard 0)
menus100command, location (palette, view/title, view/item, statusBar, explain/toolbar), view, group
  • IDs von Befehlen, Ansichten, Panels, Statusleisten-Einträgen und Einstellungen: Buchstaben, Ziffern, ., _, -, höchstens 128 Zeichen. Sie müssen über alle installierten Extensions eindeutig sein.
  • view/title und view/item brauchen view mit einer eigenen Ansicht.
  • Symbole in Baumansichten: folder, file, database, table, eye, code, package, star, braces; andere Namen erscheinen als file.

API

Die Extension exportiert activate(context, api) und optional deactivate(). context enthält extensionId, extensionPath, storagePath und subscriptions; dort abgelegte Disposables räumt l8db beim Deaktivieren auf.

import type { ExtensionContext, L8dbApi } from "@l8db/extension-api";

export function activate(context: ExtensionContext, api: L8dbApi) {
  context.subscriptions.push(api.commands.registerCommand("hello.greet", async () => {
    const active = await api.database.getActive();
    await api.notifications.showInfo(active ? `Verbunden mit ${active.name}` : "Keine Datenbank");
  }));
}

export function deactivate() {}
BereichFunktionenBerechtigung
commandsregisterCommand, executeCommand, getCommands–
eventsonDatabaseOpened, onDatabaseClosed, onActiveDatabaseChangeddatabase:read
notificationsshowInfo, showWarning, showError (ohne Aktionen als Toast, mit bis zu 5 Aktionen als Dialog)–
configurationget, onDidChange–
databasegetActive() → {connectionId, name, kind}; query(sql, params) → {columns, rows, rowsAffected, executionTimeMs}database:read, schreibend zusätzlich database:write
networkfetch(url, {method, headers, body, timeoutMs}) → {status, headers, body}network
secretsget, set, deletefilesystem:extension-storage
storageget, setfilesystem:extension-storage
clipboardreadText, writeTextclipboard:read / clipboard:write
workspaceshowOpenDialog, showSaveDialog, readTextFile, writeTextFilefilesystem
processrun(command, {args, cwd, env, timeoutMs}) → {status, stdout, stderr}process:execute
windowshowQuickPick, showInputBox, showInformationMessage, showWarningMessage, showErrorMessage–
viewssetTreeData(viewId, items), reveal(viewId)–
statusBarset(itemId, {text, tooltip, command, background}), hide(itemId)–
panelsopen(panelId, html), close, postMessage, onDidReceiveMessage; derzeit ohne sichtbare Wirkung–
assetsreadText(path) aus dem Paket–
loggerinfo, warn, error–

Hinweise zur API:

  • executeCommand auf Befehle anderer Extensions setzt eine Abhängigkeit in dependencies voraus, und die andere Extension muss bereits aktiv sein.
  • getCommands() liefert Objekte mit id, owner, title und icon, obwohl der Typ string[] angibt.
  • showQuickPick gibt die gewählten Einträge als Objekte {label, description, detail, picked} zurück, auch wenn Strings übergeben wurden.
  • statusBar.set darf nur eigene Befehle als command nutzen; text 1–120 Zeichen, background info, warning oder error.

Grenzen

BereichGrenze
SQLAbfrage bis 32 KiB, höchstens 100 Parameter
Netzwerknur HTTPS, nur Hosts aus dem Manifest, Methoden GET, POST, PUT, PATCH, DELETE, HEAD; höchstens 20 Header, Body bis 256 KiB, Antwort bis 1 MiB, Zeitlimit 1–30.000 ms (Standard 15.000), keine Weiterleitungen
Dateiennur Pfade aus dem Datei-Dialog der laufenden Sitzung; Schreiben bis 1 MiB
Speicherstorage.json bis 1 MiB; Schlüssel a-z A-Z 0-9 _ -, 1–80 Zeichen
GeheimnisseSchlüssel wie beim Speicher, Wert bis 16 KiB, im Schlüsselbund als extension:<id>:<schlüssel>
ZwischenablageSchreiben bis 256 KiB
Prozessenur Programme aus capabilities.process.commands, ohne Shell, über PATH gesucht; höchstens 50 Argumente (je 4096 Zeichen), 20 Umgebungsvariablen, Zeitlimit 1–120.000 ms (Standard 30.000); stdout und stderr je bis 512 KiB
Ansichtenhöchstens 500 Einträge, Tiefe 8
Quick Pickhöchstens 200 Einträge

Sandbox

  • Jede Extension läuft in einem unsichtbaren, abgeschotteten iframe (sandbox="allow-scripts", ohne eigenen Ursprung) und darin in einem Web Worker.
  • Sie hat keinen Zugriff auf DOM, Tauri oder direktes fetch; alles läuft über die API.
  • Antwortet eine Extension 10 Sekunden nicht oder schickt sie mehr als 500 Nachrichten pro Sekunde, gilt sie als fehlgeschlagen.
  • Argumente eines API-Aufrufs sind auf 64 KiB begrenzt, Baumdaten für Ansichten auf 280 KB.