RayMigrator

A professional database migration framework for .NET that manages versioned schema migrations across multiple database engines.

Features

• Multi-Database Support — SQL Server, PostgreSQL, MariaDB, MySQL, SQLite
• Versioned Migrations — Track schema changes across releases with file-based migration scripts
• Rollback Support — Automatic rollback on error with configurable strategies (Terminate, Rollback, RollbackRelease)
• Hash Validation — Detect unauthorized changes to executed migration files
• Transaction Control — Per-migration transaction configuration, respecting database-specific capabilities
• Environment-Specific Migrations — Target different environments and database targets with a single configuration
• Execution Modes — Run migrations simultaneously or successively across target groups
• Resilience — Retry logic, orphaned run detection, and recovery procedures
• Plugin Architecture — Extensible with custom database providers via the DAL plugin system

Supported Databases

Database	Statement Separator	DDL Transactions
SQL Server	GO	Full
PostgreSQL	;	Full
MariaDB	;	Limited
MySQL	;	Limited
SQLite	;	Full

Quick Start

Installation

# Clone and build
git clone https://github.com/RAYCOON/RayMigrator.git
cd RayMigrator
dotnet build

Minimal Configuration

Create appsettings.json in the working directory:

{
  "RayMigrator": {
    "Repository": {
      "DatabaseType": "SqlServer",
      "ConnectionString": "Server=localhost;Database=MyApp;Trusted_Connection=True;TrustServerCertificate=True",
      "SchemaName": "migrations"
    },
    "Products": [{
      "Alias": "MyProduct",
      "MigrationFilesRootDirectory": "./Migrations",
      "TargetGroups": [{
        "Alias": "Backend",
        "DatabaseType": "SqlServer",
        "Targets": [{
          "Alias": "MainDB",
          "ConnectionString": "Server=localhost;Database=MyApp;Trusted_Connection=True;TrustServerCertificate=True"
        }]
      }]
    }]
  }
}

Run Migrations

# Apply all pending migrations
RayMigrator Migrate-Up --product MyProduct --environment Production --run-mode Migrate

# Simulate without executing
RayMigrator Migrate-Up --product MyProduct --environment Production --run-mode Simulate

# View migration status
RayMigrator Info --product MyProduct --environment Production

# Validate file integrity
RayMigrator Validate-Hash --product MyProduct --environment Production

# Rollback to a specific release
RayMigrator Migrate-Down --product MyProduct --environment Production --to-release "Release 1.0" --run-mode Migrate

Migration File Format

/*
[RayMigrator]
Description = "Create user authentication tables"
Environments = ["*"]
Targets = ["*"]
UseTransaction = true
RunAlways = false
*/

CREATE TABLE Users (
    Id INT IDENTITY(1,1) PRIMARY KEY,
    Username NVARCHAR(100) NOT NULL
);

Migration files use TOML metadata in a SQL comment header. See Migration File Specification for details.

Documentation

Comprehensive documentation is available in the Docs/ folder:

• Architecture Overview
• Core Concepts
• Configuration Reference
• CLI Command Reference
• Migration File Specification
• Extending RayMigrator (custom database providers)
• User Manual (step-by-step tutorial)

Building from Source

# Build (all target frameworks)
dotnet build -c Release

# Run unit tests
dotnet test Raycoon.RayMigrator.Tests.Unit/

# Run integration tests (requires Docker)
docker-compose -f Testing/Docker/docker-compose.yml --env-file Testing/Docker/default.env up -d
dotnet test Raycoon.RayMigrator.Tests.Integration/

System Requirements

• .NET 8.0, 9.0, or 10.0
• 4 GB RAM minimum
• Windows 10+, Ubuntu 24.04+, or macOS 10.15+

NuGet Packages

RayMigrator is available as NuGet packages for integration into your own applications:

Package	Description
Raycoon.RayMigrator.Core	Domain models, configuration, and validation
Raycoon.RayMigrator.Services	Migration business logic
Raycoon.RayMigrator.Infrastructure	Template caching and utilities
Raycoon.RayMigrator.Database	DAL factory and plugin discovery
Raycoon.RayMigrator.Database.SqlServer	SQL Server provider
Raycoon.RayMigrator.Database.PostgreSQL	PostgreSQL provider
Raycoon.RayMigrator.Database.MariaDb	MariaDB provider
Raycoon.RayMigrator.Database.MySql	MySQL provider
Raycoon.RayMigrator.Database.Sqlite	SQLite provider

RayMigrator Management

For teams that need a web-based management platform with centralized configuration, API access, and multi-user support, see RayMigrator Management — the commercial management platform built on the RayMigrator engine.

Contributing

We welcome bug reports and feature requests. See CONTRIBUTING.md for details.

License

RayMigrator is licensed under the Business Source License 1.1.

You may use RayMigrator freely for internal production use. The license restricts offering RayMigrator as a commercial migration service to third parties. Each version converts to Apache 2.0 four years after its first public release.

For commercial licensing inquiries, contact info@raycoon.com.