Migrations

Database-agnostic schema migrations for .NET, driven by YAML. The DataProviderMigrate CLI tool reads a YAML schema definition and applies it to SQLite or PostgreSQL — with support for tables, columns, primary keys, foreign keys, indexes, and more.

Raw schema.sql files are intentionally not supported. YAML schemas are the single source of truth so a migration behaves identically on every target database.

Install

dotnet new tool-manifest
dotnet tool install DataProviderMigrate --version 0.9.6-beta

This registers the DataProviderMigrate command via the local tool manifest (.config/dotnet-tools.json).

Optional libraries — only needed if you embed migration logic inside your own application code:

dotnet add package Nimblesite.DataProvider.Migration.Core   --version 0.9.6-beta
dotnet add package Nimblesite.DataProvider.Migration.SQLite --version 0.9.6-beta

Commands

Command Purpose
migrate Apply a YAML schema to a target database
export Export an existing C# schema class to a YAML file

Applying a schema

# SQLite
dotnet DataProviderMigrate migrate \
  --schema example-schema.yaml \
  --output app.db \
  --provider sqlite

# PostgreSQL
dotnet DataProviderMigrate migrate \
  --schema example-schema.yaml \
  --output "Host=localhost;Database=mydb;Username=user;Password=pass" \
  --provider postgres

Exporting a schema

dotnet DataProviderMigrate export \
  --assembly ./bin/Debug/net10.0/MyApp.dll \
  --type MyApp.Schemas.InvoiceSchema \
  --output invoice-schema.yaml

YAML schema format

name: example
tables:
  - name: Customer
    schema: main
    columns:
      - name: Id
        type: Text
        isNullable: false
      - name: CustomerName
        type: Text
        isNullable: false
      - name: Email
        type: Text
        isNullable: true
    primaryKey:
      columns:
        - Id

  - name: Invoice
    schema: main
    columns:
      - name: Id
        type: Text
        isNullable: false
      - name: CustomerId
        type: Text
        isNullable: false
      - name: Amount
        type: Real
        isNullable: false
    primaryKey:
      columns:
        - Id
    foreignKeys:
      - columns:
          - CustomerId
        referencedTable: Customer
        referencedColumns:
          - Id
        onDelete: NoAction

Rules

  • Every table must have a single primary key.
  • Primary keys must be UUIDs (Text at the column level, generated by your application).
  • Foreign keys reference tables by name; onDelete accepts NoAction, Cascade, SetNull, or Restrict.
  • Supported column types include Text, Integer, Real, Blob, Boolean, DateTime, Guid, and vector types on PostgreSQL.

Wiring into MSBuild

Regenerate the database on every build so developers never run migrations manually:

<Target Name="RunDataProviderMigrate" BeforeTargets="CoreCompile">
  <Exec Command="dotnet DataProviderMigrate migrate --schema example-schema.yaml --output app.db --provider sqlite" />
</Target>

Projects

Project Description
DataProviderMigrate CLI tool (dotnet tool install DataProviderMigrate)
Nimblesite.DataProvider.Migration.Core Core migration engine
Nimblesite.DataProvider.Migration.SQLite SQLite DDL emitter
Nimblesite.DataProvider.Migration.Postgres PostgreSQL DDL emitter