CSharpDB v4.3.0 introduces migration tooling for a job that should be boring but rarely is: moving an existing schema and its data into a new database without hiding conversions, losing the ability to resume, or declaring success before the result has been checked.
The tools use one review-first workflow across file formats and database sources:
inspect and capture
↓
plan and preview
↓
apply or resume into a new staged database
↓
validate schema, counts, and checksums
↓
activate only after validation passesA Retained Source, Not a Moving Target
The first command captures the source into a provider-specific retained package and writes a catalog. The package is create-new, digest-pinned, and bound to the catalog by a SHA-256 manifest digest. Planning reads the frozen catalog; apply, resume, and validation requalify the retained package instead of quietly reconnecting to a database that may have changed.
| Source | v4.3.0 route |
|---|---|
| CSV and JSON / NDJSON | Retained import with explicit reader, inference, null, and type policy |
| SQLite and LiteDB 5 | Retained database snapshot with provider-specific schema and row handling |
| MySQL 8.0 / 8.4 | Bounded retained InnoDB table route through an isolated worker |
| Microsoft Access | Windows-only ACE candidate capture; planning remains gated pending its VM matrix |
| SQL Server | Snapshot-isolated candidate capture; planning remains gated pending the broader live release matrix |
A Complete SQLite-to-CSharpDB Run
SQLite is the shortest example because it needs no server credential or optional worker. Start in a private directory and choose new output paths:
csharpdb migrate inspect `
--source sqlite `
--input .\legacy.db `
--package .\legacy.csdbsqlite `
--out .\catalog.json
# Record the printed value in trusted change control.
$digest = 'sha256:<64-lowercase-hex>'
csharpdb migrate type-map .\catalog.json `
--profile preserve `
--out .\type-map.txt
csharpdb migrate plan .\catalog.json --out .\plan.json
csharpdb migrate preview .\plan.json --catalog .\catalog.json --ddl
csharpdb migrate preview .\plan.json --catalog .\catalog.json --scratch
New-Item -ItemType Directory -Force `
-Path .\migration-work, .\migration-spill | Out-Null
csharpdb migrate apply .\plan.json `
--catalog .\catalog.json `
--source-package .\legacy.csdbsqlite `
--expected-manifest-digest $digest `
--workspace .\migration-work `
--target .\staged.csdb `
--out .\run.json
csharpdb migrate validate .\plan.json `
--catalog .\catalog.json `
--source-package .\legacy.csdbsqlite `
--expected-manifest-digest $digest `
--workspace .\migration-work `
--target .\staged.csdb `
--out .\validation.json `
--level checksum `
--spill-dir .\migration-spillApply writes rows and target-owned receipts in the same transactions. If the process is interrupted, repeat the exact binding with --resume. The target receipts—not an orphaned workspace or a console log—decide which verified batches can be skipped.
Compatibility Is Evidence, Not a Green Checkmark
The type-map command uses the same mapping provider as migration planning and shows every exact, lossless-reencoded, lossy, or unsupported conversion. The query checker accepts bounded read-only CSharpDB SQL and, through the optional SQL Server worker, qualified T-SQL grammars. A root integer TOP can produce a review candidate using CSharpDB LIMIT.
A static result remains Conditional when schema binding, typed parameters, scratch execution, or result equivalence has not been proven. MySQL, SQLite, and Access query dialects return Unknown until their own parsers are qualified.
Validate the Copy Before Cutover
Migration validation compares normalized schema, 64-bit row counts, and partitioned canonical SHA-256 evidence against the same retained source package. A successful copy stops in an awaiting-validation state; a failed or inconclusive report keeps the staged target inactive.
For selected read-only query packs, the dual-run SDK can add result-level evidence between coherent source and target snapshots. It requires typed parameters, explicit endpoint snapshot identities obtained from trusted capture evidence, a reviewed SQL allowlist, and provider-enforced read-only access. It is deliberately not a generic connection-string CLI or a production dual-write system.
Know Which Lanes Are Still Gated
sysadmin metadata proof in the LocalDB fixture, but its supported-edition, published-runtime, platform, authentication, and differential matrix remains incomplete. Their blockers cannot be overridden, and granting broader privileges is not a valid substitute for qualification.
MySQL has an environment-gated live qualification harness, but a successful retained package test is not a blanket claim for every server build, authentication plugin, TLS configuration, or MySQL-compatible product. Provider qualification stays explicit.
Export Is Part of the Same Assurance Story
The release also exports a normal CSharpDB database to lossless CSV, JSON, or NDJSON. Export begins with an explicit offline retained snapshot, requires the snapshot identity on publication, writes a source-bound manifest, and can resume from a verified row boundary. The hardened resumable publisher is currently Windows-only; other platforms fail with a stable diagnostic instead of weakening the publication contract.
For every option, source limitation, recovery rule, and security boundary, continue with the complete database migration guide. Release archives and checksums are listed on the downloads page.