Minimig

Minimig is a forward-only, database migrator for SQL Server, PostgreSQL and MySQL.

Build Status

Appveyor	Branch	Coverage
	master

Packages

Package	NuGet (Stable)	MyGet (Prerelease)
Minimig

Installation

Easiest installation is via dotnet global tools running dotnet tool install --global Minimig from your terminal.

To install the prerelease version (from myget), you can add the option --add-source https://www.myget.org/F/minimig/api/v3/index.json

Usage

Creating Migrations

A migration is just plain T-SQL saved in a .sql file. Individual commands are separated with the GO keyword for sql server, just like when using SSMS.

In the case of mysql and postgresql, the separator used is the semicolon (;) since GO is not supported on those databases

For example:

CREATE TABLE One
(
  Id int not null identity(1,1),
  Name nvarchar(50) not null,
  
  constraint PK_One primary key clustered (Id)
)
GO

INSERT INTO One (Name) VALUES ('Person')
GO

Migrations are executed as a transaction by default, which allows them to be rolled back if any command fails. You can disable this transaction for a specific migration by beginning the file with -- no transaction --.

We recommend prefixing migration file names with a zero-padded number so that the migrations are listed in chronological order. For example, a directory of migrations might look like:

0001 - Add Users table.sql
0002 - Add Posts.sql
0003 - Insert default users.sql
0004 - Add auth columns to Users.sql
0005 - Drop tables One To Three.sql
...

Running Migrations

Migrations run from the command line, in order to allow for automation to be used.

Command Line

To run migrations the typical usage is:

mig --folder="c:\path\to\migrations" --connection="Persist Security Info=False;Integrated Security=true;Initial Catalog=MyDatabase;server=localhost" --provider=sqlserver

By default the provider used is Sql Server

If you use integrated auth, you can use the --database and --server arguments instead of supplying a connection string (server defaults to "localhost").

mig --folder="c:\\path\\to\\migrations" --database=MyLocalDatabase --server=MyServer --provider=sqlserver

Use mig --help to show the complete set of options:

Usage: Minimig [OPTIONS]+
Runs all *.sql files in the directory --f=<folder> specified.
  The databse connection can be specified using the following combinations:
  -A connection string with the --connection along a --provider
      if no provider is specified, the program defaults to sqlserver.
  -Minimig can generate an integrated auth connection string using
      the --database and optional --server arguments, along a --provider.

  -h, --help                 Shows this help message.
  -c, --connection=VALUE     A connection string (can be PostgreSQL or 
                               SQLServer or MySQL). For integrated auth, you
                               can use --database and --server instead.
  -d, --database=VALUE       Generates an integrated auth connection string
                               for the specified database.
  -s, --server=VALUE         Generates an integrated auth connection string
                               with the specified server (default: localhost).
  -f, --folder=VALUE         The folder containing your .sql migration files
                               (defaults to current working directory).
      --timeout=VALUE        Command timeout duration in seconds (default:
                               30).
      --preview              Run outstanding migrations, but roll them back.
  -p, --provider=VALUE       Use a specific database provider options:
                               sqlserver (default), postgresql, mysql.
      --global               Run all outstanding migrations in a single
                               transaction, if possible.
      --table=VALUE          Name of the table used to track migrations
                               (default: Migrations).
      --schema=VALUE         Name of the schema to be used to track
                               migrations (default: dbo for sqlserver, public
                               for postgresql, mysql for mysql).
      --force                Will rerun modified migrations.
      --version              Print version number.
      --count                Print the number of outstanding migrations.

Reverting Migrations

Minimig has no such concept. It is a forward-only tool. This is done to keep a minimalistic approach.

Running Migrations on CI

It is relatively trivial to configure a docker sql image and run minimig on a ci in order to test your sql migrations, a sample is included on the following repository

Uninstallation

For uninstallation execute dotnet tool uninstall --global Minimig from terminal.

Contributing

Contributions are welcome. Before opening a pull request, build the project and run the full test suite locally, including the integration tests that require a live database connection.

Building and testing

Use your favorite editor, but from the terminal to build run: dotnet build

To run tests: dotnet test --project ./tests/MinimigTests.csproj --framework net10.0

This repository targets .NET 10 and uses global.json to enable Microsoft Testing Platform mode for dotnet test.

After building, run the CI coverage command with dotnet test --project ./tests/MinimigTests.csproj --framework net10.0 --no-restore --coverlet --coverlet-output-format cobertura --results-directory ./TestResults. The build restores dependencies, so CI skips restoring them again during testing.

Testing locally with Docker

The integration tests under tests/Integration require live SQL Server, PostgreSQL, and MySQL instances. Use Docker to provision these databases locally.

1. Start the databases from the repository root:

   docker compose -f .docker/docker-compose.yml --env-file .docker/.env up -d
   

   This provisions:

   • PostgreSQL 13 on localhost:5432 (user postgres, password Password12!, database postgres)
   • MySQL (latest) on localhost:3306 (empty root password, database test)
   • SQL Server 2019 on localhost:1433 (user sa, password P@ssword123)

2. Set connection string env variables to match the containers. Use tcp:127.0.0.1,1433 explicitly for SQL Server.

   $env:Sql_Connection = "Server=tcp:127.0.0.1,1433;Database=master;User Id=sa;Password=P@ssword123;TrustServerCertificate=True;"
   $env:Postgres_Connection = "Server=localhost;Port=5432;Database=postgres;Username=postgres;Password=Password12!;"
   $env:MySql_Connection = "Server=127.0.0.1;Port=3306;Database=test;User Id=root;"
   

3. Run the tests:

   dotnet test --project ./tests/MinimigTests.csproj --framework net10.0
   

4. Tear down the containers when finished:

   docker compose -f .docker/docker-compose.yml down
   

Credit

This library started as a fork from Mayflower.net which is inactive

License

Minimig is available under the MIT License

Logo license

Minimig's icon was created by Freepik under Creative Commons license 3.0