24601/surreal-skills

Habilidade SurrealDB 3

Arquitetura, desenvolvimento e operações de nível especialista para SurrealDB 3. Abrange SurrealQL, modelagem de dados multi-modelo, travessia de grafos, busca vetorial, segurança, implantação, otimização de desempenho, integração de SDKs e o ecossistema SurrealDB mais amplo, incluindo SurrealKit, SurrealMCP, n8n, CodeMirror e superfícies de habilidades para agentes.

Para Agentes de IA

Obtenha um manifesto completo de capacidades, árvores de decisão e contratos de saída:

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

Consulte AGENTS.md para o briefing estruturado completo.

Comando	O Que Faz
uv run {baseDir}/scripts/doctor.py	Verificação de integridade: verificar CLI surreal, conectividade, versões
uv run {baseDir}/scripts/doctor.py --check	Verificação rápida de aprovado/reprovado (apenas código de saída)
uv run {baseDir}/scripts/schema.py introspect	Despejar esquema completo de uma instância SurrealDB em execução
uv run {baseDir}/scripts/schema.py tables	Listar todas as tabelas com contagens de campos e índices
uv run {baseDir}/scripts/onboard.py --agent	Manifesto de capacidades JSON para integração com agente

Pré-requisitos

• CLI surreal -- brew install surrealdb/tap/surreal (macOS) ou veja a documentação de instalação
• Python 3.10+ -- Necessário para scripts da habilidade
• uv -- brew install uv (macOS) ou pip install uv ou veja a documentação do uv

Opcional:

• Docker -- Para instâncias SurrealDB em contêiner (docker run surrealdb/surrealdb:v3)
• SDK de sua escolha -- JavaScript, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift ou Ruby

Nota de segurança: Esta habilidade documenta apenas instalações via gerenciador de pacotes e contêiner. Prefira instalações auditáveis através de Homebrew, apt/dnf, Cargo, npm ou Docker em vez de instaladores remoto de linha única via shell.

Início Rápido

Aviso de credenciais: Os exemplos abaixo usam root/root apenas para desenvolvimento local. Nunca use credenciais padrão contra instâncias de produção ou compartilhadas. Crie usuários com escopo e privilégios mínimos para ambientes não locais.

# Iniciar SurrealDB em memória APENAS PARA DESENVOLVIMENTO LOCAL
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Iniciar com armazenamento persistente RocksDB (desenvolvimento local)
surreal start rocksdb://data/mydb.db --user root --pass root

# Iniciar com SurrealKV (consultas com viagem no tempo suportadas, desenvolvimento local)
surreal start surrealkv://data/mydb --user root --pass root

# Conectar via REPL da CLI (desenvolvimento local)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Importar um arquivo SurrealQL
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql

# Exportar a base de dados
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql

# Verificar versão
surreal version

# Executar a verificação de integridade da habilidade
uv run {baseDir}/scripts/doctor.py

Variáveis de Ambiente

Variável	Descrição	Padrão
SURREAL_ENDPOINT	URL do servidor SurrealDB	http://localhost:8000
SURREAL_USER	Nome de usuário root ou do namespace	root
SURREAL_PASS	Senha root ou do namespace	root
SURREAL_NS	Namespace padrão	test
SURREAL_DB	Base de dados padrão	test

Estas mapeiam diretamente para os sinalizadores da CLI surreal sql (--endpoint, --user, --pass, --ns, --db) e são reconhecidas pelos SDKs oficiais do SurrealDB.

Capacidades Principais

Domínio do SurrealQL

Cobertura completa da linguagem de consulta SurrealQL: CREATE, SELECT, UPDATE, UPSERT, DELETE, RELATE, INSERT, LIVE SELECT, DEFINE, REMOVE, INFO, subconsultas, transações, futuros e todas as funções embutidas (array, crypto, duration, geo, math, meta, object, parse, rand, string, time, type, vector).

Consulte: rules/surrealql.md

Modelagem de Dados Multi-Modelo

Projete esquemas que aproveitam as capacidades multi-modelo do SurrealDB -- coleções de documentos, arestas de grafos, referências relacionais, embeddings vetoriais, dados de séries temporais e coordenadas geoespaciais -- tudo em uma única base de dados com uma única linguagem de consulta.

Consulte: rules/data-modeling.md

Consultas de Grafo

Travessia de grafos de primeira classe sem JOINs. RELATE cria arestas tipadas entre registros. Atravesse com operadores -> (saída), <- (entrada) e <-> (bidirecional). Filtre, agregue e faça recursão em qualquer profundidade.

Consulte: rules/graph-queries.md

Busca Vetorial

Busca de similaridade vetorial embutida usando índices HNSW (o tipo de índice vetorial v3; força bruta está disponível como fallback durante a construção/recriação do índice). Defina campos vetoriais, crie índices com métricas de distância configuráveis (cosseno, euclidiana, manhattan, minkowski) e consulte com funções vector::similarity::*. Construa pipelines RAG e busca semântica diretamente em SurrealQL.

Consulte: rules/vector-search.md

Segurança e Permissões

Segurança em nível de linha via DEFINE TABLE ... PERMISSIONS, controle de acesso em nível de namespace/base de dados/registro, DEFINE ACCESS para autenticação baseada em JWT/token, DEFINE USER para usuários do sistema e variáveis de tempo de execução $auth/$session para predicados de permissão.

Consulte: rules/security.md

Implantação e Operações

Implantação com um único binário, Docker, Kubernetes (Helm charts), seleção de mecanismo de armazenamento (memory, RocksDB, SurrealKV, TiKV para distribuído), backup/restauração, monitoramento e endurecimento de produção.

Consulte: rules/deployment.md

Otimização de Desempenho

Estratégias de índices (unique, search, vector HNSW), otimização de consultas com EXPLAIN, pooling de conexões, compensações de mecanismo de armazenamento, operações em lote e limites de recursos.

Consulte: rules/performance.md

Integração de SDKs

SDKs oficiais para JavaScript/TypeScript (Node.js, Deno, Bun, navegador), Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift (iOS/macOS/visionOS) e Ruby. Inclui a ligação C apenas com fonte, limite da API não lançada do Python v3, superfície beta do .NET v0.10.2, protocolos de conexão, fluxos de autenticação, assinaturas de consultas ao vivo e manipulação de registros tipados.

Consulte: rules/sdks.md

Extensões WASM Surrealism

Novo no SurrealDB 3: estenda a base de dados com funções personalizadas, analisadores e lógica escritos em Rust e compilados para WASM. Defina, implante e gerencie módulos Surrealism.

Consulte: rules/surrealism.md

Inferência em Base de Dados SurrealML (prévia / instável)

surrealml tem um lançamento no GitHub v0.1.2, mas o PyPI ainda expõe surrealml 0.0.4 como o pacote mais recente a partir deste instantâneo. O formato de artefato .surml e os extras [sklearn], [torch], [tensorflow] são o limite documentado estável. A documentação v1.4.0 para DEFINE MODEL, INFO FOR MODEL, REMOVE MODEL, ml::name<version>(...), surreal ml import, db.upload_ml(...), e os métodos de fábrica SurMlFile.from_<framework>(...) foi retirada no v1.4.1. O caminho de configuração Python atual baixa bibliotecas nativas dos GitHub Releases a menos que LOCAL_BUILD=TRUE, então fixe e audite antes do uso em produção.

Consulte: rules/surrealml.md

SurrealMCP -- Servidor Model Context Protocol

O servidor MCP oficial (surrealdb/surrealmcp) permite que hosts de IA compatíveis com MCP (Claude Desktop, Cursor, GitHub Copilot no VS Code, Zed, n8n) leiam e escrevam no SurrealDB através de uma entrada de configuração. Instale a partir do código fonte (cargo install --path .) ou Docker; não está no crates.io ou npm. O binário requer o subcomando start. Os nomes das ferramentas são em snake_case: query, select, insert, create, upsert, update, delete, relate, connect_endpoint, use_namespace, use_database, list_namespaces, list_databases, disconnect_endpoint, além de ferramentas de nuvem.

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

Ferramentas de Editor

surrealql-language-server v0.1.3 é a linha de base do LSP de primeira parte; surql-lsp v0.1.1 continua sendo um crate comunitário separado. A regra rastreia tree-sitter, extensões de editor de primeira parte e @surrealdb/codemirror / @surrealdb/lezer v1.0.5 para editores web personalizados. Paletas de comando e configurações por extensão ainda precisam do README de cada extensão como fonte da verdade.

Consulte: rules/editor-tooling.md

Integração LangChain (apenas Python)

langchain-surrealdb 0.2.1 (Python; langchain-core ~= 1.1.0, surrealdb ~= 1.0.8 SDK v1) expõe o SurrealDB como um armazenamento vetorial através do construtor SurrealDBVectorStore(embeddings, conn). O pacote JS, classe assíncrona, histórico de chat e recuperador híbrido do v1.4.0 foram retirados no v1.4.1.

Consulte: rules/langchain.md

Integrações de Ecossistema

Superfícies de documentação oficial e adjacentes de primeira parte que ainda não são regras dedicadas completas: @surrealdb/n8n-nodes-surrealdb v0.6.0 para n8n auto-hospedado, o índice de documentação oficial de frameworks de IA, Spectron / Agent Memory Context como apenas roadmap, pacotes CodeMirror e o repositório oficial surrealdb/agent-skills. Use esta regra para evitar apresentar páginas de roadmap ou ponteiros como APIs de produção.

Consulte: rules/ecosystem-integrations.md

Ferramentas do Ecossistema

• Surrealist -- IDE oficial e GUI para SurrealDB (designer de esquemas, editor de consultas, visualizador de grafos)
• Surreal-Sync -- Change Data Capture (CDC) para migrações de outras bases de dados
• SurrealFS -- Sistema de arquivos para agentes de IA construído sobre SurrealDB
• SurrealKit -- Sincronização de esquemas com estado desejado, migrações baseadas em rollout, semeadura e testes declarativos
• SurrealML -- Ferramentas de artefato .surml em estágio de pré-visualização; superfície de invocação do servidor ainda instável
• SurrealMCP -- Servidor Model Context Protocol para agentes de IA
• n8n -- Pacote comunitário oficial com escopo para workflows n8n auto-hospedados
• CodeMirror -- Pacotes oficiais de sintaxe SurrealQL para editores personalizados
• setup-surreal -- GitHub Action oficial (surrealdb/setup-surreal@v2) para executar SurrealDB em workflows CI. Não é um bootstrap de CLI (a documentação v1.4.0 que o descrevia como tal foi retirada no v1.4.2)

Consulte: 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 (seção setup-surreal)

Doctor / Verificação de Integridade

# Diagnóstico completo (saída Rich no stderr, JSON no stdout)
uv run {baseDir}/scripts/doctor.py

# Verificação rápida (código de saída 0 = saudável, 1 = problemas encontrados)
uv run {baseDir}/scripts/doctor.py --check

# Verificar um endpoint específico
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000

O script doctor verifica: CLI surreal instalada e no PATH, servidor acessível, autenticação bem-sucedida, namespace e base de dados existentes, compatibilidade de versão e status do mecanismo de armazenamento.

Introspecção de Esquemas

# Despejo completo do esquema (todas as tabelas, campos, índices, eventos, acessos)
uv run {baseDir}/scripts/schema.py introspect

# Listar tabelas com resumo
uv run {baseDir}/scripts/schema.py tables

# Inspecionar uma tabela específica
uv run {baseDir}/scripts/schema.py table <table_name>

# Exportar esquema como SurrealQL (instruções DEFINE reproduzíveis)
uv run {baseDir}/scripts/schema.py export --format surql

# Exportar esquema como JSON
uv run {baseDir}/scripts/schema.py export --format json

A introspecção usa INFO FOR DB, INFO FOR TABLE e INFO FOR NS para reconstruir o esquema completo.

Referência de Regras

Arquivo de Regra	Cobertura
rules/surrealql.md	Sintaxe SurrealQL, instruções, funções, operadores, expressões idiomáticas
rules/data-modeling.md	Design de esquemas, IDs de registros, tipos de campo, relações, normalização
rules/graph-queries.md	RELATE, operadores de travessia de grafos, expressões de caminho, consultas recursivas
rules/vector-search.md	Campos vetoriais, índices HNSW (o tipo de índice vetorial v3), funções de similaridade, padrões RAG
rules/security.md	Permissões, controle de acesso, autenticação, JWT, segurança em nível de linha
rules/deployment.md	Instalação, mecanismos de armazenamento, Docker, Kubernetes, configuração de produção; GitHub Action surrealdb/setup-surreal@v2 (apenas CI; não é um bootstrap de CLI)
rules/performance.md	Índices, EXPLAIN, otimização de consultas, operações em lote, ajuste de recursos
rules/sdks.md	Uso dos SDKs JS/TS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby, padrões de conexão, consultas ao vivo
rules/surrealism.md	Extensões WASM, funções personalizadas, criação de módulos Surrealism
rules/surrealml.md	Escopo de pré-visualização do SurrealML, artefatos .surml, limites de pacote/versão, aviso de dependência nativa
rules/surrealmcp.md	Servidor Model Context Protocol: catálogo de ferramentas, configuração do host, transportes, implantação
rules/editor-tooling.md	LSP, gramática tree-sitter, CodeMirror, extensões VS Code / JetBrains / Neovim / Helix / Sublime / Zed
rules/langchain.md	Integração LangChain Python: armazenamento vetorial, API do construtor, limite custom_filter
rules/ecosystem-integrations.md	n8n, índice de documentação de frameworks de IA, limite do roadmap Spectron, CodeMirror, repositório oficial Agent Skills
rules/surrealist.md	Uso do IDE/GUI Surrealist, designer de esquemas, editor de consultas
rules/surreal-sync.md	Ferramenta de migração CDC, conectores de origem/destino, workflows de migração
rules/surrealfs.md	Sistema de arquivos para agente de IA, armazenamento de arquivos, metadados, padrões de recuperação
rules/surrealkit.md	Sincronização de esquemas com estado desejado, migrações baseadas em rollout, semeadura e testes declarativos de DB
rules/gotchas.md	Casos de borda e armadilhas entre domínios: upgrade, grafo, vetor, segurança, MCP, SDKs (v3.1.4+)

Exemplos de Workflow

Todos os exemplos de workflow usam root/root apenas para desenvolvimento local. Para produção, use DEFINE USER com credenciais com escopo e privilégios mínimos.

Configuração de Novo Projeto

# 1. Verificar ambiente
uv run {baseDir}/scripts/doctor.py

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

# 3. Projetar esquema (use rules/data-modeling.md para orientação)
# 4. Importar esquema inicial
surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production schema.surql

# 5. Introspecção para verificar
uv run {baseDir}/scripts/schema.py introspect

Migração a partir do SurrealDB Anterior

… [truncado para tradução]