24601/surreal-skills

SurrealKit -- Gestión de Esquemas para Aplicaciones SurrealDB

SurrealKit gestiona esquemas de aplicaciones SurrealDB como archivos .surql de estado deseado, con rutas separadas para bases de datos de desarrollo desechables y para implementaciones compartidas o de producción.

Instantánea upstream rastreada: v0.6.3 pre-release (7771b93ea563, 2026-05-13). La línea de parches v0.6.1 -> v0.6.3 añadió correcciones de bloqueo de librería, variables de plantilla, limpieza de comentarios, manejo de DROP ... IF EXISTS y cobertura de DEFINE para BUCKET, SEQUENCE y CONFIG.

Inicio Rápido

# Instalar
cargo binstall surrealkit
# o: cargo install surrealkit

# Crear estructura de proyecto
surrealkit init

# Reconciliar base de datos local/desechable con archivos de esquema locales
surrealkit sync

# Generar y aplicar una migración revisada para compartido/producción
surrealkit rollout plan --name agregar_indices_clientes
surrealkit rollout start 20260410120000__agregar_indices_clientes
surrealkit rollout complete 20260410120000__agregar_indices_clientes

Comandos Principales

Comando	Uso
surrealkit sync	Reconciliación de estado deseado para bases de datos locales, previsualización o desechables
surrealkit sync --watch	Bucle de desarrollo local con vigilancia de archivos
surrealkit rollout baseline	Establecer seguimiento de migraciones en una base de datos compartida existente
surrealkit rollout plan --name <nombre>	Crear un manifiesto revisado a partir del diff actual del esquema
surrealkit rollout start <id>	Aplicar la fase de expansión
surrealkit rollout complete <id>	Aplicar la fase de contracción/destructiva después del corte
surrealkit rollout rollback <id>	Revertir una migración en curso
surrealkit rollout lint <id>	Validar una migración sin mutar la base de datos
surrealkit rollout status	Inspeccionar el estado de la migración almacenado en la base de datos
surrealkit seed	Aplicar datos de semilla
surrealkit test	Ejecutar pruebas declarativas de esquema, permisos y API

Cuándo Usarlo

• Usa sync cuando la base de datos debe reflejar los archivos locales inmediatamente.
• Usa rollout cuando los cambios necesitan etapas, revisión, reversión o corte controlado.
• Usa seed para datos de fixture deterministas.
• Usa test en CI para validar permisos, comportamiento del esquema y contratos de API.

Entorno

SurrealKit lee estas variables:

• 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)

Pruebas

Las suites declarativas en database/tests/suites/*.toml admiten:

• sql_expect
• permissions_matrix
• schema_metadata
• schema_behavior
• api_request

Ejemplo:

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

Documentación Completa

Consulta la regla principal de la skill para la guía operativa completa:

• rules/surrealkit.md -- estrategia sync vs rollout, variables de entorno, semillas, pruebas declarativas y patrones de CI
• surrealdb/surrealkit -- repositorio upstream