24601/surreal-skills

SurrealKit – Gerenciamento de Esquemas para Aplicações SurrealDB

O SurrealKit gerencia esquemas de aplicações SurrealDB como arquivos .surql de estado desejado, com caminhos separados para bancos de dados descartáveis de desenvolvimento e para rollouts compartilhados ou de produção.

Snapshot upstream rastreado: v0.6.3 pré-lançamento (7771b93ea563, 2026-05-13). A linha de patches v0.6.1 → v0.6.3 adicionou correções de travamento de biblioteca, variáveis de modelo, limpeza de remoção de comentários, tratamento de DROP ... IF EXISTS e cobertura de DEFINE para BUCKET, SEQUENCE e CONFIG.

Início Rápido

# Instalação
cargo binstall surrealkit
# ou: cargo install surrealkit

# Estrutura de projeto inicial
surrealkit init

# Reconciliação do banco local/descartável com os arquivos de esquema local
surrealkit sync

# Geração e aplicação de um rollout revisado para compartilhado/produção
surrealkit rollout plan --name add_customer_indexes
surrealkit rollout start 20260410120000__add_customer_indexes
surrealkit rollout complete 20260410120000__add_customer_indexes

Comandos Principais

Comando	Uso
surrealkit sync	Reconciliação de estado desejado para bancos locais, preview ou descartáveis
surrealkit sync --watch	Loop de desenvolvimento local com monitoramento de arquivos
surrealkit rollout baseline	Estabelecer rastreamento de rollout em um banco compartilhado existente
surrealkit rollout plan --name <nome>	Criar um manifesto revisado a partir da diferença do esquema atual
surrealkit rollout start <id>	Aplicar a fase de expansão
surrealkit rollout complete <id>	Aplicar a fase de contrato/destrutiva após a migração
surrealkit rollout rollback <id>	Reverter um rollout em andamento
surrealkit rollout lint <id>	Validar um rollout sem modificar o banco de dados
surrealkit rollout status	Inspecionar o estado do rollout armazenado no banco de dados
surrealkit seed	Aplicar dados de semeadura
surrealkit test	Executar testes declarativos de esquema, permissão e API

Quando Usar

• Use sync quando o banco de dados deve espelhar os arquivos locais imediatamente.
• Use rollout quando as mudanças precisam de preparação, revisão, reversão ou migração controlada.
• Use seed para dados de fixture determinísticos.
• Use test em CI para validar permissões, comportamento do esquema e contratos de API.

Ambiente

O SurrealKit lê estas variáveis:

• SURREALDB_HOST (fallback: DATABASE_HOST)
• SURREALDB_NAME (fallback: DATABASE_NAME)
• SURREALDB_NAMESPACE (fallback: DATABASE_NAMESPACE)
• SURREALDB_USER (fallback: DATABASE_USER)
• SURREALDB_PASSWORD (fallback: DATABASE_PASSWORD)
• SURREALDB_AUTH_LEVEL (fallback: DATABASE_AUTH_LEVEL)

Testes

As suítes declarativas em database/tests/suites/*.toml suportam:

• sql_expect
• permissions_matrix
• schema_metadata
• schema_behavior
• api_request

Exemplo:

surrealkit test --fail-fast --json-out artifacts/surrealkit-tests.json

Documentação Completa

Consulte a regra principal da skill para orientação operacional completa:

• rules/surrealkit.md — estratégia sync vs rollout, variáveis de ambiente, semeaduras, testes declarativos e padrões de CI
• surrealdb/surrealkit — repositório upstream