MigLib 8.0.0

Migrate is a SQLite-first migration toolchain built around a DomainModeling project, generated Db.fs, and compiled schema modules. It generates typed CRUD/query helpers from compiled schema definitions and provides blocking init, plan, migrate, status, and reset workflows for schema-bound SQLite files.

Project Convention

The current convention is:

1. Keep the runtime project in the working directory.
2. Keep the domain modeling project at DomainModeling/DomainModeling.fsproj.
3. Keep the schema source at DomainModeling/MigSchema.fs.
4. Run mig codegen from the runtime project directory.
5. Let mig codegen write Db.fs into the domain modeling directory.
6. Build the runtime project after code generation so the compiled runtime assembly contains the generated module.

MigSchema.fs must mark the schema module with GeneratedDbNamespace:

[<MigLib.Dsl.Attributes.GeneratedDbNamespace("MyApp")>]
module MyApp.DomainModeling.MigSchema

mig codegen uses that attribute to generate MyApp.Db and derive the SQLite filename prefix.

Generated Code

mig codegen emits a runtime module that contains:

• GeneratedSchema
• generated record and DU types
• generated CRUD/query helpers driven by schema annotations

Examples of generated helpers include:

• Student.Insert
• Student.InsertOrIgnore
• Student.SelectById
• Student.SelectAll
• Student.SelectByName
• Student.SelectNameLike
• Student.SelectByNameOrInsert
• Student.Upsert

Installation

Install the CLI as a global tool:

dotnet tool install --global migtool

For library usage:

• install MigLib for schema attributes, generated CRUD support, transactions, and migration workflows
• install MigLib.Web when you also want the ASP.NET Core webResult helpers

Local Tool Build

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

dotnet fsi build.fsx install

Quickstart: Init

Build the domain modeling project, generate Db.fs, build the runtime project, and initialize the schema-bound database:

dotnet build ./my-app/DomainModeling/DomainModeling.fsproj
mig codegen -d ./my-app
dotnet build ./my-app/my-app.fsproj
mig init -d ./my-app

mig init is idempotent at the workflow level: when the target database already exists, it reports success and does not recreate it.

Quickstart: Migrate

When a previous schema-bound SQLite file already exists for the same app/instance prefix, mig migrate creates the new target database, copies compatible data, and archives the old file into archive/ next to the database directory.

dotnet build ./my-app/DomainModeling/DomainModeling.fsproj
mig codegen -d ./my-app
dotnet build ./my-app/my-app.fsproj
mig plan -d ./my-app
mig migrate -d ./my-app
mig status -d ./my-app

If you need to discard the current target database and restore the latest archived database back into the main database directory:

mig reset -d ./my-app

Runtime Use

Generated helpers execute inside dbTxn or txn transaction workflows.

open System.IO
open MigLib
open MigLib.MigProject
open MyApp.Db

let project =
  MigProject.Mig.resolveFromGeneratedSchema dataDirectory None GeneratedSchema
  |> fun task -> task.Result
  |> Result.defaultWith (fun error -> failwithf "%A" error)

let db = dbTxn project.targetDbPath

let result =
  db {
    let! student = Student.SelectByNameOrInsert { Id = 0L; Name = "Alice"; Age = 21L }
    let! matches = Student.SelectNameLike "li"
    return student, matches
  }

Example

example/ shows the full convention in a working project:

• runtime project at example/example.fsproj
• domain modeling project at example/DomainModeling/DomainModeling.fsproj
• generated Db.fs at example/DomainModeling/Db.fs
• generated CRUD usage in example/Program.fs
• scripted init and migrate flows in example/build.fsx

Run it with:

dotnet fsi example/build.fsx

Commands

• mig codegen: generate Db.fs from the compiled DomainModeling project and MigSchema.fs source file
• mig init: create the current schema-bound database when it does not exist yet
• mig plan: report inferred source/target paths plus supported and unsupported schema differences
• mig migrate: create the target database, copy data, and archive the previous source database
• mig status: show the current database path, archived databases, and whether a migration source is still present
• mig reset: delete the current target database and restore the latest archived database into the main database directory

Specs

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

Contributing

• Open an issue to discuss the change and approach.
• Add relevant tests.
• Open a pull request with the problem statement and solution summary.

License

Apache 2.0