Help us improve
Share bugs, ideas, or general feedback.
Share bugs, ideas, or general feedback.
Share bugs, ideas, or general feedback.
By necmttn
Complete SurrealDB v2 to v3 migration toolkit - custom SurQL parser, schema transformer, backup restore, and migration playbook
npx claudepluginhub necmttn/surrealdb-v2-to-v3Battle-tested tools for migrating SurrealDB from v2.x to v3.x. Built after discovering that the official surreal export/import roundtrip fails on real-world databases with backslash escaping, compound record IDs, and multi-line INSERT statements.
Tested on a production database: 119,962 records migrated with zero failures.
scripts/surrealdb-migrate.ts - Custom SurQL parser + CBOR-over-WebSocket importer with checkpoint/resumescripts/surrealdb-restore-sdk.ts - SDK-based restore that fixes v2's backslash escaping bugscripts/rid-to-surql.ts - RecordId-to-SurrealQL serializer (fixes SDK v2's broken toString() for compound IDs)docs/breaking-changes.md - Complete v2-to-v3 breaking changes referencedocs/playbook.md - Step-by-step production migration playbookdocs/benchmarks.md - Real-world migration benchmarks and impact assessmentgit clone https://github.com/necmttn/surrealdb-v2-to-v3.git
cd surrealdb-v2-to-v3
bun install
curl -X GET http://localhost:8000/export \
-H "NS: your_ns" -H "DB: your_db" \
-H "Authorization: Basic $(echo -n 'root:root' | base64)" \
-o backup.surql
# Full migration with v3 schema transformations
bun run scripts/surrealdb-migrate.ts backup.surql \
--url http://localhost:8000 \
--user root --pass root \
--ns your_ns --db your_db \
--v3
# Dry run first to assess
bun run scripts/surrealdb-migrate.ts backup.surql --dry-run
| Flag | Default | Description |
|---|---|---|
--url | http://localhost:8000 | SurrealDB URL |
--user | root | Username |
--pass | root | Password |
--ns | prod | Namespace |
--db | prod | Database |
--batch | 50 | Records per insert batch |
--v3 | off | Apply v3 schema transformations |
--data-only | off | Skip schema, only import INSERT data |
--dry-run | off | Parse and report without importing |
surreal import?The official surreal export + surreal import roundtrip breaks on:
\boldsymbol, file paths). v3's parser rejects them.block:[document:xxx, '/path'] aren't supported by the text importer.This toolkit solves all of these by parsing the SurQL export into JS objects and using the SDK's CBOR binary protocol over WebSocket.
See Troubled Migrations for detailed examples with real data patterns showing exactly how each failure manifests and how the custom tools handle them.
This repo includes a Claude Code skill for AI-assisted migration.
# From your project directory
claude plugin install github://necmttn/surrealdb-v2-to-v3
/surrealdb-migrate ./path/to/schema/or/backup
The skill provides:
Handles the full SurQL export format including:
block:[document:xxx, '/path'])table:⟨uuid⟩)d'...') and UUID (u'...') literalsCrash recovery built-in. If migration fails mid-way, re-run the same command to resume from the last checkpoint.
Handles WebSocket disconnections with up to 3 retries and exponential backoff.
When a batch insert fails, automatically falls back to inserting records one-by-one to maximize data recovery.
The --v3 flag automatically transforms function names and syntax in schema statements during import.
MIT
Share bugs, ideas, or general feedback.
Based on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
Manage database migrations with version control, rollback capabilities, and automated schema evolution tracking
Generate database migrations and code migration scripts for framework upgrades
Safe database and system migration patterns - dual write, shadow mode, strangler fig
將 Flyway SQL 遷移腳本轉換為 OSC (Online Schema Change) 格式,支援 ALTER TABLE 和 CREATE INDEX 語句的自動轉換
Skills for migrating dbt projects — moving from dbt Core to the Fusion engine or across data platforms.
Comprehensive skill pack with 66 specialized skills for full-stack developers: 12 language experts (Python, TypeScript, Go, Rust, C++, Swift, Kotlin, C#, PHP, Java, SQL, JavaScript), 10 backend frameworks, 6 frontend/mobile, plus infrastructure, DevOps, security, and testing. Features progressive disclosure architecture for 50% faster loading.
ax - the agent experience layer. Local graph of every Claude Code + Codex session, skill invocation, edit, and commit. Surfaces what to use, what to ground on, and which experiments to package next.
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claim