MigLib.Web 5.2.1

Migrate is a SQLite-first migration toolchain built around Schema.fs, generated Db.fs, and compiled schema modules. It provides both a hot-migration workflow (migrate → drain → cutover) and a one-shot offline workflow (offline), plus type-safe code generation from compiled schema types.

Schema Project Convention

The recommended layout is to keep Schema.fs in its own Schema.fsproj, build that project first, and then generate Db.fs from the compiled schema assembly before compiling the main application project.

This convention exists to eliminate build dependency cycles:

• generating Db.fs needs a compiled schema assembly
• compiling the main application project usually needs the generated Db.fs

When mig runs in a directory that contains Schema.fsproj, it tries to discover the compiled schema assembly automatically by looking for:

1. bin/Debug/net10.0/<AssemblyName>.dll when <AssemblyName> is set in Schema.fsproj
2. bin/Debug/net10.0/Schema.dll otherwise

If there is no Schema.fsproj, mig falls back to the single-.fsproj convention and looks for bin/Debug/net10.0/<ProjectName>.dll.

All compiled-module commands can still be overridden with the optional --assembly and --module parameters.

Installation

If you just want to test the tool without installing .Net, then you can use a Docker image:

podman run -it 'mcr.microsoft.com/dotnet/sdk:10.0' bash

Inside the container run:

export PATH="$PATH:/root/.dotnet/tools"

After having .Net in your system you can run

dotnet tool install --global migtool

For library usage:

• install MigLib when you only need the database/runtime surface
• install MigLib.Web in addition when you want ASP.NET Core webResult helpers

Local Tool Build/Install (FAKE)

Build, pack, and install the current branch as a global mig tool from the local package output:

dotnet fsi build.fsx

Run specific FAKE targets when needed:

dotnet fsi build.fsx -- --target Build
dotnet fsi build.fsx -- --target PackTool

Run the installed local tool directly:

mig --help

Quickstart (Online Migration)

Assuming:

• an existing SQLite database named <dir>-<old-hash>.sqlite
• a compiled generated Db module produced from Schema.fs
• the recommended Schema.fsproj convention above

# from your project directory:
mig codegen
mig plan
mig migrate

# then continue in the same directory (paths auto-resolve)
mig status
mig drain
mig cutover
# optional, after traffic has fully moved to the new service:
mig archive-old

# from a different directory:
mig migrate -d /path/to/project

# if migrate fails and you need to clear failed migration artifacts:
mig reset --dry-run
mig reset

Quickstart (Schema Initialization)

When you want to bootstrap a database directly from a compiled generated Db module (no source DB yet):

mig codegen
mig init

Quickstart (Offline Migration)

When downtime is acceptable and you want to create the fully migrated target DB in one command from a compiled generated Db module:

mig codegen
mig offline

Library Example

The CLI automates the same startup decision that MigLib.HotMigration.startService exposes directly in application code.

open System.Threading
open Mig.HotMigration
open Db

let sqliteDirectoryEnvVar = "APP_SQLITE_DIRECTORY"

let startRuntime cancellationToken =
  task {
    let! result =
      startService
        sqliteDirectoryEnvVar
        Db.DbFile
        Db.SchemaIdentity
        Db.Schema
        cancellationToken

    match result with
    | Ok db -> return db
    | Error ex -> return raise ex
  }

startService will:

• use the ready database immediately when the current schema-bound file already exists
• initialize a fresh database when no previous database is found
• migrate from the previous database when exactly one non-target sqlite file is discovered in the configured directory
• fail startup when previous-database inference is ambiguous or the target database is invalid

Features

• Schema reflection from compiled F# modules
• FK-aware bulk copy and replay with ID mapping
• Replay checkpoints and drain safety validation
• Schema identity metadata (schema_hash, optional schema_commit) persisted in new database
• Operational status reporting for old/new database migration state
• Optional old-database archival into archive/ after cutover
• Transactional ASP.NET Core request composition via the separate MigLib.Web package and webResult

Specs

• specs/database_dsl.md
• specs/hot_migrations.md
• specs/mig_command.md
• specs/operator_runbook.md
• specs/web_result.md

Commands

• mig codegen - Generate Db.fs from Schema.fs plus the compiled schema module, and emit a DbFile literal for the schema-bound SQLite filename.
• mig init - Create a schema-matched database from the compiled generated module and apply seed inserts when the database does not exist yet.
• mig plan - Print inferred paths, schema diff summary, and replay prerequisites without mutating databases.
• mig migrate - Create the new database, bulk-copy data, and start recording new writes on the old database.
• mig drain - Switch the old database to draining mode and replay pending migration log entries.
• mig cutover - Verify drain completion, switch the new database to ready, and remove replay-only tables.
• mig offline - Create the fully migrated target database in one step and archive the old database into archive/.
• mig archive-old - Archive the old database into archive/, replacing any existing archive with the same name.
• mig reset - Reset failed or aborted migration artifacts, or inspect reset impact first with --dry-run.
• mig status - Show marker/status state and migration counters for operational visibility.

Contributing

How to contribute:

• Open an issue to discuss the change and approach
• Add relevant tests
• Create a pull request mentioning the issue and also including a summary of the problem and approach to solve it
• Wait for the review

Acknowledgments

This project wouldn't have been possible without the amazing open-source community. We're especially grateful to:

• Fabulous.AST - An elegant F# DSL for code generation that made creating and manipulating F# AST a joy
• Fantomas - The excellent F# code formatter that ensures our generated code is beautiful and consistent

If you find these projects valuable, please consider supporting them:

• Star their repositories
• Contribute to their projects
• Donate to support their continued development

License

Apache 2.0