24601/surreal-skills

SurrealDB 3 Skill

Expertenwissen für SurrealDB 3 Architektur, Entwicklung und Betrieb. Deckt SurrealQL, Multi-Modell-Datenmodellierung, Graph-Traversierung, Vektorsuche, Sicherheit, Deployment, Performance-Tuning, SDK-Integration und das gesamte SurrealDB-Ökosystem ab, einschließlich SurrealKit, SurrealMCP, n8n, CodeMirror und Agent-Skill-Oberflächen.

Für KI-Agenten

Rufen Sie ein vollständiges Fähigkeitenmanifest, Entscheidungsbäume und Ausgabe-Contracts ab:

uv run {baseDir}/scripts/onboard.py --agent

Siehe AGENTS.md für die vollständige strukturierte Einweisung.

Befehl	Beschreibung
uv run {baseDir}/scripts/doctor.py	Gesundheitscheck: Überprüft surreal CLI, Konnektivität, Versionen
uv run {baseDir}/scripts/doctor.py --check	Schnellprüfung bestanden/nicht bestanden (nur Exit-Code)
uv run {baseDir}/scripts/schema.py introspect	Vollständiges Schema einer laufenden SurrealDB-Instanz ausgeben
uv run {baseDir}/scripts/schema.py tables	Alle Tabellen mit Feldanzahl und Indizes auflisten
uv run {baseDir}/scripts/onboard.py --agent	JSON-Fähigkeitenmanifest für Agentenintegration

Voraussetzungen

• surreal CLI -- brew install surrealdb/tap/surreal (macOS) oder siehe Installationsdokumentation
• Python 3.10+ -- Erforderlich für Skill-Skripte
• uv -- brew install uv (macOS) oder pip install uv oder siehe uv-Dokumentation

Optional:

• Docker -- Für containerisierte SurrealDB-Instanzen (docker run surrealdb/surrealdb:v3)
• SDK der Wahl -- JavaScript, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift oder Ruby

Sicherheitshinweis: Dieser Skill dokumentiert nur Paketmanager- und Container-Installationen. Bevorzugen Sie überprüfbare Installationen über Homebrew, apt/dnf, Cargo, npm oder Docker anstelle von entfernten Einzeiler-Shell-Installern.

Schnellstart

Credential-Warnung: Die Beispiele unten verwenden root/root nur für lokale Entwicklung. Verwenden Sie niemals Standard-Anmeldeinformationen gegen Produktions- oder gemeinsam genutzte Instanzen. Erstellen Sie bereichsbezogene Benutzer mit minimalen Berechtigungen für Nicht-Lokale-Umgebungen.

# SurrealDB im Arbeitsspeicher starten NUR FÜR LOKALE ENTWICKLUNG
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Mit persistentem RocksDB-Speicher starten (lokale Entwicklung)
surreal start rocksdb://data/mydb.db --user root --pass root

# Mit SurrealKV starten (Zeitreise-Abfragen unterstützt, lokale Entwicklung)
surreal start surrealkv://data/mydb --user root --pass root

# Über CLI-REPL verbinden (lokale Entwicklung)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Eine SurrealQL-Datei importieren
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql

# Die Datenbank exportieren
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql

# Version prüfen
surreal version

# Den Skill-Gesundheitscheck ausführen
uv run {baseDir}/scripts/doctor.py

Umgebungsvariablen

Variable	Beschreibung	Standard
SURREAL_ENDPOINT	SurrealDB-Server-URL	http://localhost:8000
SURREAL_USER	Root- oder Namespace-Benutzername	root
SURREAL_PASS	Root- oder Namespace-Passwort	root
SURREAL_NS	Standard-Namespace	test
SURREAL_DB	Standard-Datenbank	test

Diese werden direkt auf die surreal sql CLI-Flags (--endpoint, --user, --pass, --ns, --db) abgebildet und von den offiziellen SurrealDB-SDKs erkannt.

Kernfähigkeiten

SurrealQL-Meisterschaft

Vollständige Abdeckung der SurrealQL-Abfragesprache: CREATE, SELECT, UPDATE, UPSERT, DELETE, RELATE, INSERT, LIVE SELECT, DEFINE, REMOVE, INFO, Unterabfragen, Transaktionen, Future-Werte und alle integrierten Funktionen (Array, Crypto, Duration, Geo, Math, Meta, Object, Parse, Rand, String, Time, Type, Vector).

Siehe: rules/surrealql.md

Multi-Modell-Datenmodellierung

Entwerfen Sie Schemata, die die Multi-Modell-Fähigkeiten von SurrealDB nutzen – Dokumentensammlungen, Graph-Kanten, relationale Referenzen, Vektor-Embeddings, Zeitreihendaten und geografische Koordinaten – alles in einer einzigen Datenbank mit einer einzigen Abfragesprache.

Siehe: rules/data-modeling.md

Graph-Abfragen

Graph-Traversierung erster Klasse ohne JOINs. RELATE erstellt typisierte Kanten zwischen Datensätzen. Traversieren Sie mit den Operatoren -> (ausgehend), <- (eingehend) und <-> (bidirektional). Filtern, aggregieren und rekursieren Sie in jeder Tiefe.

Siehe: rules/graph-queries.md

Vektorsuche

Integrierte Vektor-Ähnlichkeitssuche mit HNSW-Indizes (der v3-Vektor-Index-Typ; Brute-Force ist als Fallback während des Index-Aufbaus/Neubaus verfügbar). Definieren Sie Vektorfelder, erstellen Sie Indizes mit konfigurierbaren Distanzmetriken (Cosinus, Euklidisch, Manhattan, Minkowski) und fragen Sie mit vector::similarity::*-Funktionen ab. Bauen Sie RAG-Pipelines und semantische Suche direkt in SurrealQL.

Siehe: rules/vector-search.md

Sicherheit und Berechtigungen

Zeilenebenen-Sicherheit via DEFINE TABLE ... PERMISSIONS, Zugriffskontrolle auf Namespace-/Datenbank-/Datensatzebene, DEFINE ACCESS für JWT/token-basierte Authentifizierung, DEFINE USER für Systembenutzer und $auth/$session-Laufzeitvariablen für Berechtigungsprädikate.

Siehe: rules/security.md

Deployment und Betrieb

Single-Binary-Deployment, Docker, Kubernetes (Helm-Charts), Speicher-Engine-Auswahl (memory, RocksDB, SurrealKV, TiKV für verteilten Betrieb), Backup/Restore, Monitoring und Produktionshärtung.

Siehe: rules/deployment.md

Performance-Tuning

Indexstrategien (unique, search, vector HNSW), Abfrageoptimierung mit EXPLAIN, Verbindungspooling, Speicher-Engine-Abwägungen, Batch-Operationen und Ressourcenlimits.

Siehe: rules/performance.md

SDK-Integration

Offizielle SDKs für JavaScript/TypeScript (Node.js, Deno, Bun, Browser), Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift (iOS/macOS/visionOS) und Ruby. Beinhaltet die reine C-Bindung, die unveröffentlichte Python-v3-API-Grenze, die .NET v0.10.2 Beta-Oberfläche, Verbindungsprotokolle, Authentifizierungsabläufe, Live-Abfrage-Abonnements und die Handhabung typisierter Datensätze.

Siehe: rules/sdks.md

Surrealism WASM-Erweiterungen

Neu in SurrealDB 3: Erweitern Sie die Datenbank mit benutzerdefinierten Funktionen, Analysatoren und Logik, die in Rust geschrieben und zu WASM kompiliert wurden. Definieren, bereitstellen und verwalten Sie Surrealism-Module.

Siehe: rules/surrealism.md

SurrealML In-Database-Inferenz (Vorschau / instabil)

surrealml hat eine GitHub-Version v0.1.2, aber PyPI stellt noch surrealml 0.0.4 als neuestes Paket zum Zeitpunkt dieser Momentaufnahme bereit. Das .surml-Artefaktformat und die Zusatzpakete [sklearn], [torch], [tensorflow] sind die stabile dokumentierte Grenze. Die Dokumentation v1.4.0 für DEFINE MODEL, INFO FOR MODEL, REMOVE MODEL, ml::name<version>(...), surreal ml import, db.upload_ml(...) und die SurMlFile.from_<framework>(...)-Factory-Methoden wurde in v1.4.1 zurückgezogen. Der aktuelle Python-Setup-Pfad lädt native Bibliotheken von GitHub-Releases herunter, es sei denn, LOCAL_BUILD=TRUE ist gesetzt; daher vor dem Produktionseinsatz einfrieren und prüfen.

Siehe: rules/surrealml.md

SurrealMCP – Model Context Protocol Server

Der offizielle MCP-Server (surrealdb/surrealmcp) ermöglicht MCP-kompatiblen KI-Hosts (Claude Desktop, Cursor, GitHub Copilot in VS Code, Zed, n8n) das Lesen und Schreiben von SurrealDB über einen einzigen Konfigurationseintrag. Installation aus dem Quellcode (cargo install --path .) oder Docker; nicht auf crates.io oder npm. Das Binary erfordert den Unterbefehl start. Die Werkzeug-Drahtnamen sind snake_case: query, select, insert, create, upsert, update, delete, relate, connect_endpoint, use_namespace, use_database, list_namespaces, list_databases, disconnect_endpoint, plus Cloud-Werkzeuge.

Siehe: rules/surrealmcp.md, skills/surrealmcp/SKILL.md

Editor-Tools

surrealql-language-server v0.1.3 ist die First-Party-LSP-Basislinie; surql-lsp v0.1.1 bleibt eine separate Community-Crate. Die Regel verfolgt tree-sitter, First-Party-Editor-Erweiterungen und @surrealdb/codemirror / @surrealdb/lezer v1.0.5 für benutzerdefinierte Web-Editoren. Pro-Erweiterungs-Befehlspaletten und -Einstellungen benötigen weiterhin die README jeder Erweiterung als Quelle der Wahrheit.

Siehe: rules/editor-tooling.md

LangChain-Integration (nur Python)

langchain-surrealdb 0.2.1 (Python; langchain-core ~= 1.1.0, surrealdb ~= 1.0.8 v1 SDK) stellt SurrealDB als Vektor-Store über den Konstruktor SurrealDBVectorStore(embeddings, conn) bereit. JS-Paket, async-Klasse, Chat-Verlauf und hybrider Retriever aus v1.4.0 wurden in v1.4.1 zurückgezogen.

Siehe: rules/langchain.md

Ökosystem-Integrationen

Offizielle Dokumentations- und First-Party-nahe Oberflächen, die noch keine vollständigen dedizierten Regeln sind: @surrealdb/n8n-nodes-surrealdb v0.6.0 für selbst gehostetes n8n, der offizielle KI-Framework-Dokumentationsindex, Spectron / Agent Memory Context als reine Roadmap, CodeMirror-Pakete und das offizielle surrealdb/agent-skills-Repository. Verwenden Sie diese Regel, um Roadmap- oder Verweis-Seiten nicht als Produktions-APIs darzustellen.

Siehe: rules/ecosystem-integrations.md

Ökosystem-Werkzeuge

• Surrealist – Offizielle IDE und GUI für SurrealDB (Schema-Designer, Abfrage-Editor, Graph-Visualizer)
• Surreal-Sync – Change Data Capture (CDC) für Migrationen von anderen Datenbanken
• SurrealFS – KI-Agenten-Dateisystem, basierend auf SurrealDB
• SurrealKit – Soll-Zustand Schema-Synchronisation, Rollout-basierte Migrationen, Seeding und deklarative Tests
• SurrealML – Vorschauphase .surml-Artefakt-Tooling; Server-Aufrufoberfläche noch instabil
• SurrealMCP – Model Context Protocol-Server für KI-Agenten
• n8n – Offizielles bereichsbezogenes Community-Paket für selbst gehostete n8n-Workflows
• CodeMirror – Offizielle SurrealQL-Syntax-Pakete für benutzerdefinierte Editoren
• setup-surreal – Offizielle GitHub-Aktion (surrealdb/setup-surreal@v2) zum Ausführen von SurrealDB in CI-Workflows. Kein CLI-Bootstrap (die Dokumentation v1.4.0, die es als solchen beschrieb, wurde in v1.4.2 zurückgezogen)

Siehe: rules/surrealist.md, rules/surreal-sync.md, rules/surrealfs.md, rules/surrealkit.md, rules/surrealml.md, rules/surrealmcp.md, rules/ecosystem-integrations.md, rules/deployment.md (Abschnitt setup-surreal)

Doctor / Gesundheitscheck

# Vollständige Diagnose (Rich-Ausgabe auf stderr, JSON auf stdout)
uv run {baseDir}/scripts/doctor.py

# Schnellprüfung (Exit-Code 0 = gesund, 1 = Probleme gefunden)
uv run {baseDir}/scripts/doctor.py --check

# Bestimmten Endpunkt prüfen
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000

Das Doctor-Skript überprüft: surreal CLI installiert und im PATH, Server erreichbar, Authentifizierung erfolgreich, Namespace und Datenbank vorhanden, Versionskompatibilität und Speicher-Engine-Status.

Schema-Introspection

# Vollständiger Schema-Dump (alle Tabellen, Felder, Indizes, Events, Zugriffe)
uv run {baseDir}/scripts/schema.py introspect

# Tabellen mit Zusammenfassung auflisten
uv run {baseDir}/scripts/schema.py tables

# Bestimmte Tabelle inspizieren
uv run {baseDir}/scripts/schema.py table <table_name>

# Schema als SurrealQL exportieren (reproduzierbare DEFINE-Anweisungen)
uv run {baseDir}/scripts/schema.py export --format surql

# Schema als JSON exportieren
uv run {baseDir}/scripts/schema.py export --format json

Die Introspection verwendet INFO FOR DB, INFO FOR TABLE und INFO FOR NS, um das vollständige Schema zu rekonstruieren.

Regeln-Referenz

Regel-Datei	Abdeckung
rules/surrealql.md	SurrealQL-Syntax, Anweisungen, Funktionen, Operatoren, Redewendungen
rules/data-modeling.md	Schema-Design, Datensatz-IDs, Feldtypen, Beziehungen, Normalisierung
rules/graph-queries.md	RELATE, Graph-Traversierungsoperatoren, Pfadausdrücke, rekursive Abfragen
rules/vector-search.md	Vektorfelder, HNSW-Indizes (der v3-Vektor-Index-Typ), Ähnlichkeitsfunktionen, RAG-Muster
rules/security.md	Berechtigungen, Zugriffskontrolle, Authentifizierung, JWT, Zeilenebenen-Sicherheit
rules/deployment.md	Installation, Speicher-Engines, Docker, Kubernetes, Produktionskonfiguration; surrealdb/setup-surreal@v2 GitHub-Aktion (nur CI; kein CLI-Bootstrap)
rules/performance.md	Indizes, EXPLAIN, Abfrageoptimierung, Batch-Operationen, Ressourcen-Tuning
rules/sdks.md	JS/TS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby SDK-Nutzung, Verbindungsmuster, Live-Abfragen
rules/surrealism.md	WASM-Erweiterungen, benutzerdefinierte Funktionen, Surrealism-Modul-Erstellung
rules/surrealml.md	SurrealML Vorschau-Umfang, .surml-Artefakte, Paket-/Release-Grenzen, Hinweis zu nativen Abhängigkeiten
rules/surrealmcp.md	Model Context Protocol-Server: Werkzeugkatalog, Host-Konfiguration, Transporte, Deployment
rules/editor-tooling.md	LSP, tree-sitter-Grammatik, CodeMirror, VS Code / JetBrains / Neovim / Helix / Sublime / Zed-Erweiterungen
rules/langchain.md	LangChain Python-Integration: Vektor-Store, Konstruktor-API, custom_filter-Grenze
rules/ecosystem-integrations.md	n8n, KI-Framework-Dokumentationsindex, Spectron-Roadmap-Grenze, CodeMirror, offizielles Agent Skills-Repository
rules/surrealist.md	Surrealist IDE/GUI-Nutzung, Schema-Designer, Abfrage-Editor
rules/surreal-sync.md	CDC-Migrationswerkzeug, Quell-/Ziel-Konnektoren, Migrations-Workflows
rules/surrealfs.md	KI-Agenten-Dateisystem, Dateispeicher, Metadaten, Abrufmuster
rules/surrealkit.md	Soll-Zustand Schema-Synchronisation, Rollout-basierte Migrationen, Seeding und deklarative DB-Tests
rules/gotchas.md	Domänenübergreifende Grenzfälle und Fallstricke: Upgrade, Graph, Vektor, Sicherheit, MCP, SDKs (v3.1.4+)

Workflow-Beispiele

Alle Workflow-Beispiele verwenden root/root nur für lokale Entwicklung. Für die Produktion verwenden Sie DEFINE USER mit bereichsbezogenen Anmeldeinformationen mit minimalen Berechtigungen.

Neues Projekt einrichten

# 1. Umgebung überprüfen
uv run {baseDir}/scripts/doctor.py

# 2. SurrealDB starten
surreal start rocksdb://data/myproject.db --user root --pass root

# 3. Schema entwerfen (verwenden Sie rules/data-modeling.md als Leitfaden)
# 4. Initiales Schema importieren
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production schema.surql

# 5. Introspection zur Überprüfung
uv run {baseDir}/scripts/schema.py introspect

Migration von Surr

…[für die Übersetzung gekürzt]