surrealkit
starsforks
How to install surrealkit?
24601/surreal-skills/surrealkit
$npx -y skills add 24601/surreal-skills --skill surrealkitSurrealKit schema sync, rollout migrations, seeding, and declarative testing for SurrealDB apps. Part of the surreal-skills collection.
SKILL.md
| 1 | # SurrealKit -- Schema Management for SurrealDB Apps |
| 2 | |
| 3 | SurrealKit manages SurrealDB application schemas as desired-state `.surql` |
| 4 | files, with separate paths for disposable development databases and shared or |
| 5 | production rollouts. |
| 6 | |
| 7 | Tracked upstream snapshot: **v0.6.3** pre-release (`7771b93ea563`, 2026-05-13). |
| 8 | The v0.6.1 -> v0.6.3 patch line added library-lock fixes, template variables, |
| 9 | comment-stripping cleanup, `DROP ... IF EXISTS` handling, and `DEFINE` coverage |
| 10 | for `BUCKET`, `SEQUENCE`, and `CONFIG`. |
| 11 | |
| 12 | ## Quick Start |
| 13 | |
| 14 | ```bash |
| 15 | # Install |
| 16 | cargo binstall surrealkit |
| 17 | # or: cargo install surrealkit |
| 18 | |
| 19 | # Scaffold project structure |
| 20 | surrealkit init |
| 21 | |
| 22 | # Reconcile local/disposable database to local schema files |
| 23 | surrealkit sync |
| 24 | |
| 25 | # Generate and apply a reviewed rollout for shared/prod |
| 26 | surrealkit rollout plan --name add_customer_indexes |
| 27 | surrealkit rollout start 20260410120000__add_customer_indexes |
| 28 | surrealkit rollout complete 20260410120000__add_customer_indexes |
| 29 | ``` |
| 30 | |
| 31 | ## Core Commands |
| 32 | |
| 33 | | Command | Use | |
| 34 | |---------|-----| |
| 35 | | `surrealkit sync` | Desired-state reconciliation for local, preview, or disposable DBs | |
| 36 | | `surrealkit sync --watch` | Local development loop with file watching | |
| 37 | | `surrealkit rollout baseline` | Establish rollout tracking on an existing shared DB | |
| 38 | | `surrealkit rollout plan --name <name>` | Create a reviewed manifest from current schema diff | |
| 39 | | `surrealkit rollout start <id>` | Apply the expansion phase | |
| 40 | | `surrealkit rollout complete <id>` | Apply the contract/destructive phase after cutover | |
| 41 | | `surrealkit rollout rollback <id>` | Roll back an in-flight rollout | |
| 42 | | `surrealkit rollout lint <id>` | Validate a rollout without mutating the DB | |
| 43 | | `surrealkit rollout status` | Inspect rollout state stored in the DB | |
| 44 | | `surrealkit seed` | Apply seed data | |
| 45 | | `surrealkit test` | Run declarative schema, permission, and API tests | |
| 46 | |
| 47 | ## When to Use It |
| 48 | |
| 49 | - Use `sync` when the database should mirror local files immediately. |
| 50 | - Use `rollout` when changes need staging, review, rollback, or controlled cutover. |
| 51 | - Use `seed` for deterministic fixture data. |
| 52 | - Use `test` in CI to validate permissions, schema behavior, and API contracts. |
| 53 | |
| 54 | ## Environment |
| 55 | |
| 56 | SurrealKit reads these variables: |
| 57 | |
| 58 | - `SURREALDB_HOST` (fallback: `DATABASE_HOST`) |
| 59 | - `SURREALDB_NAME` (fallback: `DATABASE_NAME`) |
| 60 | - `SURREALDB_NAMESPACE` (fallback: `DATABASE_NAMESPACE`) |
| 61 | - `SURREALDB_USER` (fallback: `DATABASE_USER`) |
| 62 | - `SURREALDB_PASSWORD` (fallback: `DATABASE_PASSWORD`) |
| 63 | - `SURREALDB_AUTH_LEVEL` (fallback: `DATABASE_AUTH_LEVEL`) |
| 64 | |
| 65 | ## Testing |
| 66 | |
| 67 | Declarative suites in `database/tests/suites/*.toml` support: |
| 68 | |
| 69 | - `sql_expect` |
| 70 | - `permissions_matrix` |
| 71 | - `schema_metadata` |
| 72 | - `schema_behavior` |
| 73 | - `api_request` |
| 74 | |
| 75 | Example: |
| 76 | |
| 77 | ```bash |
| 78 | surrealkit test --fail-fast --json-out artifacts/surrealkit-tests.json |
| 79 | ``` |
| 80 | |
| 81 | ## Full Documentation |
| 82 | |
| 83 | See the main skill rule for full operating guidance: |
| 84 | - **[rules/surrealkit.md](../../rules/surrealkit.md)** -- sync vs rollout strategy, env vars, seeds, declarative tests, and CI patterns |
| 85 | - **[surrealdb/surrealkit](https://github.com/surrealdb/surrealkit)** -- upstream repository |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
