Chd.Library.Migrations 8.6.4

Migration Library for .NET Core

📝 Table of Contents

• About
• Features
• Quick Start
• How Migrations Are Applied
• Database Integration (DI)
  • PostgreSQL
  • Oracle
  • MsSQL
  • SQLite
  • On-demand Migration
• Configuration
• Writing Migrations
  • Schema Migration Example
  • Data Migration Example
  • Comprehensive Fluent Migration Reference
• Advanced Usage & Best Practices
• Production Tips & Troubleshooting
• FAQ
• Feature Comparison
• Authors
• Acknowledgements

About

Chd.Library.Migration is a production-ready, attribute-based, fluent database migration library for .NET Core.
Manage schema and data versioning for PostgreSQL, Oracle, MsSQL, and SQLite using clean C# and a proven migration approach.
No more SQL scripts or CLI headaches—get full control, auditability, and speed in all environments.

Features

• Attribute-based versioned migrations: [Migration(version, author)]
• Powerful fluent DSL for all schema/data operations: Create, Alter, Drop, Insert, Update, Delete, Index, Constraints, Execute SQL, and more.
• Auto-discovers all migration classes in your project (no manual registration)
• Runs all pending migrations automatically at app startup, in a background thread for speed and safety
• Tracks migration history using a dedicated VersionInfo table
• Supports both startup and on-demand migration triggers
• Fully thread-safe, standardized and production tested
• .NET 9.0+ support

Quick Start

1. Install:

   dotnet add package Chd.Library.Migration
   

2. Configure your connection strings:

   "ConnectionStrings": {
     "PostgreSQLTest": "Host=localhost;Port=5432;Database=my_db;User ID=postgres;Password=xxx;",
     "OracleTest":"Data Source=...;User Id=...;Password=...;",
     "MsSQLTest": "Server=...;Database=...;User Id=...;Password=...;",
     "SQLiteTest": "Data Source=mydb.db;"
   }
   

3. Register your migration(s) in DI (choose the database you use):

   // In Program.cs
   builder.Services.AddMigration<Program>(DatabaseType.PostgreSQL, "PostgreSQLTest");
   

🚦 How Migrations Are Applied

• Automatic & Threaded:
  On application startup, all pending migrations are executed in a background thread—keeping startup blazing-fast and never blocking the API/UI.
• On-demand, anywhere:
  Trigger migrations anytime with DatabaseMigration.RunMigration<T>(...) (CLI tools, admin panels, deployment hooks, etc.).
• Single Source of Truth:
  The VersionInfo table records migration versioning and prevents accidental or duplicate runs—ensuring safety across all environments.
• Production-Proven:
  Battle-tested in multiple enterprise, microservice, and critical app deployments.

Database Integration (DI)

PostgreSQL

builder.Services.AddMigration<Program>(DatabaseType.PostgreSQL, "PostgreSQLTest");

Oracle

builder.Services.AddMigration<Program>(DatabaseType.Oracle, "OracleTest");

MsSQL

builder.Services.AddMigration<Program>(DatabaseType.MsSQL, "MsSQLTest");

SQLite

builder.Services.AddMigration<Program>(DatabaseType.SQLite, "SQLiteTest");

On-demand Migration

DatabaseMigration.RunMigration<Program>(DatabaseType.PostgreSQL, "YourFullConnectionStringHere");

(Runs migrations on demand, in a background thread.)

Configuration

Set your databases in appsettings.json (or any .NET config provider):

"ConnectionStrings": {
  "PostgreSQLTest": "Host=localhost;Port=5432;Database=my_db;User ID=postgres;Password=xxx;",
  "OracleTest": "Data Source=...;User Id=...;Password=...;",
  "MsSQLTest": "Server=...;Database=...;User Id=...;Password=...;",
  "SQLiteTest": "Data Source=mydb.db;"
}

Writing Migrations

Schema Migration Example

[Migration(1, "Mehmet Yoldaş")]
public class StudentTableMigration : Migration
{
    public override void Up()
    {
        Create.Table("student")
            .WithIdColumn()
            .WithColumn("first_name").AsString().NotNullable()
            .WithColumn("last_name").AsString(255)
            .WithColumn("user_name").AsString()
            .WithColumn("birth_date").AsDate().Nullable();
    }
    public override void Down()
    {
        Delete.Table("student");
    }
}

Creates a table with primary key and string/date columns. Down() removes it.

Data Migration Example

[Migration(1000001, "Mehmet Yoldaş")]
public class SeedStudents : Migration
{
    public override void Up()
    {
        Insert.Into("student").Row(new { first_name = "Mehmet", last_name = "Yoldaş", user_name = "mehmetyoldas", birth_date = DateTime.Now });
        Insert.Into("student").Row(new { first_name = "Ali", last_name = "Yılmaz", user_name = "aliyilmaz", birth_date = DateTime.Now });
    }
    public override void Down()
    {
        // Remove seeded data if possible
    }
}

Inserts several rows; Down() can delete or ignore as needed.

Comprehensive Fluent Migration Reference

Below is a reference of the most common migration operations—with short explanations.

CREATE TABLE

Create.Table("users")
    .WithIdColumn()
    .WithColumn("name").AsString().NotNullable()
    .WithColumn("email").AsString(255).Unique()
    .WithColumn("created_at").AsDateTime().WithDefault(DateTime.UtcNow);

Create a table, use different column types, unique constraint, and default value.

ALTER TABLE (ADD COLUMN)

Alter.Table("users").AddColumn("is_active").AsBoolean().WithDefault(true);

Add a boolean column with default.

INSERT DATA

Insert.Into("users").Row(new { name = "Jane", email = "jane@site.com", created_at = DateTime.UtcNow });

Insert a row into a table.

UPDATE DATA

Update.Table("users").Set(new { email = "jane@newmail.com" }).Where(new { name = "Jane" });

Update matching rows using an anonymous object as WHERE filter.

DELETE DATA

Delete.From("users").Row(new { name = "Jane" });

Delete a row with matching field(s).

DROP COLUMN

Delete.Column("is_active").FromTable("users");

Remove a column.

CREATE INDEX

Create.Index("ix_users_email")
    .OnTable("users")
    .OnColumn("email")
    .Ascending()
    .Unique();

Index definition—ascending, unique.

ADD FOREIGN KEY

Create.ForeignKey("fk_orders_user")
    .FromTable("orders").ForeignColumn("user_id")
    .ToTable("users").PrimaryColumn("id")
    .OnDelete(System.Data.Rule.Cascade);

Create a foreign key with cascade.

EXECUTE RAW SQL

Execute.Sql("UPDATE users SET is_active = 1 WHERE is_active IS NULL");

Direct SQL execution for advanced or data-fix scenarios.

RENAME TABLE / COLUMN

Rename.Table("old_users").To("users");
Rename.Column("surname").OnTable("users").To("last_name");

Rename any table or column.

Advanced Usage & Best Practices

• Don’t forget Down() methods: Guarantee safe rollbacks in migrations, especially for destructive ops.
• Versioning Strategy: Use ascending integer versions; recommend < 1,000,000 for schema, ≥ 1,000,000 for data.
• Chained/Multi-table migrations: You can create highly complex migration sequences, chained Up()/Down()’s for transactional/atomic deployment strategies.
• CI/CD Ready: Migrations are designed for hands-off automation—works perfectly in scalable, cloud-native environments.

Production Tips & Troubleshooting

• Migration not running?
  • Confirm [Migration] attribute & base class; check namespace is discoverable.
  • Ensure you call the correct AddMigration<T> root class in DI.
• Migration errors:
  • Fix the migration, re-deploy—system will retry safely. Check the VersionInfo table for current state.
• Order and atomicity:
  • Always version and order migrations strictly! Never modify applied migrations—append new ones only for any fix.
• Failure Recovery:
  • Well-written Down() enables you to revert migrations if you ever need emergency rollback.

FAQ

Q: Can I use the same library for multiple databases?
Yes, register each DB via AddMigration<T>(DatabaseType, ConnectionStringKey) in DI. Each keeps its own migration chain.

Q: I want to trigger migrations from an admin panel or after deployment.
Just use the On-Demand API:

DatabaseMigration.RunMigration<Program>(DatabaseType.MsSQL, "connectionstring");

Q: Is it safe for production, CI/CD, and cloud?
Absolutely! This system is running in high-availability production SaaS, web, and microservice environments.

Q: Can I write fully custom SQL if needed?
Yes—use the Execute.Sql(...) method for any edge-case, batch, or one-off data fix.

Feature Comparison

Authors

• Mehmet Yoldaş (mehmet-yoldas)

See also contributors on NuGet

Acknowledgements

• Inspired by FluentMigrator, EF, and Flyway
• Special thanks to organizations and engineers who have tested and improved this library in critical production environments

For issues, feature requests or pull requests, visit mehmet-yoldas/library-core