24601/surreal-skills

Synchronisation de schéma, déploiement de migrations, amorçage et tests déclaratifs pour applications SurrealDB avec SurrealKit. Fait partie de la collection surreal-skills.

Qu'est-ce que surreal-skills ?

SurrealKit est un outil de gestion de schéma pour SurrealDB qui permet de traiter les définitions de schéma comme des fichiers `.surql` d'état désiré. Il prend en charge la synchronisation directe pour les bases de données locales ou jetables, et les déploiements contrôlés en plusieurs phases pour les environnements partagés ou de production. L'outil propose des commandes `sync` pour une application immédiate, `rollout` pour des migrations planifiées avec phases d'expansion et de contraction, `seed` pour les données de test, et `test` pour valider les permissions, le comportement du schéma et les contrats API de manière déclarative. Cette compétence est particulièrement utile pour les développeurs travaillant avec SurrealDB dans des environnements CI/CD, permettant des déploiements sûrs et reproductibles tout en maintenant un contrôle de version granulaire.

Compatible avec~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/24601/surreal-skills/tree/main/skills/surrealkit

Documentation

SurrealKit -- Gestion de schéma pour applications SurrealDB

SurrealKit gère les schémas d'application SurrealDB sous forme de fichiers .surql d'état désiré, avec des chemins séparés pour les bases de données de développement jetables et les déploiements partagés ou de production.

Snapshot amont suivi : v0.6.3 pré-version (7771b93ea563, 2026-05-13). La ligne de correctifs v0.6.1 -> v0.6.3 a ajouté des correctifs de verrouillage de bibliothèque, des variables de modèle, un nettoyage de suppression de commentaires, la gestion de DROP ... IF EXISTS et la couverture DEFINE pour BUCKET, SEQUENCE et CONFIG.

Démarrage rapide

# Installation
cargo binstall surrealkit
# ou : cargo install surrealkit

# Créer la structure du projet
surrealkit init

# Rapprocher la base de données locale/jetable avec les fichiers de schéma locaux
surrealkit sync

# Générer et appliquer un déploiement relu pour la base partagée/production
surrealkit rollout plan --name ajouter_index_clients
surrealkit rollout start 20260410120000__ajouter_index_clients
surrealkit rollout complete 20260410120000__ajouter_index_clients

Commandes principales

Commande	Utilisation
`surrealkit sync`	Rapprochement d'état désiré pour les bases de données locales, de prévisualisation ou jetables
`surrealkit sync --watch`	Boucle de développement local avec surveillance de fichiers
`surrealkit rollout baseline`	Établir le suivi des déploiements sur une base de données partagée existante
`surrealkit rollout plan --name <nom>`	Créer un manifeste relu à partir du diff de schéma actuel
`surrealkit rollout start <id>`	Appliquer la phase d'expansion
`surrealkit rollout complete <id>`	Appliquer la phase de contraction/destructive après la bascule
`surrealkit rollout rollback <id>`	Annuler un déploiement en cours
`surrealkit rollout lint <id>`	Valider un déploiement sans modifier la base de données
`surrealkit rollout status`	Inspecter l'état du déploiement stocké dans la base
`surrealkit seed`	Appliquer les données d'amorçage
`surrealkit test`	Exécuter les tests déclaratifs de schéma, de permissions et d'API

Quand l'utiliser

Utilisez sync lorsque la base de données doit refléter immédiatement les fichiers locaux.
Utilisez rollout lorsque les changements nécessitent une mise en scène, une relecture, un retour arrière ou une bascule contrôlée.
Utilisez seed pour des données de fixture déterministes.
Utilisez test dans l'intégration continue pour valider les permissions, le comportement du schéma et les contrats API.

Environnement

SurrealKit lit ces variables :

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

Tests

Les suites déclaratives dans database/tests/suites/*.toml prennent en charge :

sql_expect
permissions_matrix
schema_metadata
schema_behavior
api_request

Exemple :

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

Documentation complète

Consultez la règle principale pour des instructions d'utilisation complètes :

rules/surrealkit.md -- stratégie sync vs rollout, variables d'environnement, amorçage, tests déclaratifs et modèles CI
surrealdb/surrealkit -- dépôt amont