MibBulkMigrator

The MibBulkMigrator it is a tool that allows unifying various migration sources for the creation/update of a MIB environment.

Installation

Starting with MIB v6.0, MibBulkMigrator is now distributed as a dotnet tool, available as a NuGet packaging, which allows easier installation and update.

To install, you can run the following command in a terminal:

dotnet tool install -g MediaiBox.Tools.BulkMigrator --version 6.0.0

This will install MibBulkMigrator globally, and you can execute it anywhere. But if one needs to distribute this for a customer, we recommend installing it to a specific path, which can then be packaged.

For more information about dotnet tool install, please check Microsoft's documentation here.

Updating

As with any other dotnet tool, updating to the newest version just requires running the following command:

dotnet tool update MediaiBox.Tools.BulkMigrator --version 6.0.1

A MibBulkMigrator that was installed to a specific path can also be updated using the correct path parameter.

For more information about dotnet tool update, please check Microsoft's documentation here.

How does it work?

When calling the MibBulkMigrator, three parameters can be specified: -configPath, -direction, -packages.Let's explore each of them in more detail:

configPath: Path that should contain the necessary configurations for executing the MibMigrator tool. *required
direction: Specifies the execution direction of the configured migrations. *required
packages: Specifies the list of packages to be considered during execution.

Example of usage: mibbulkmigrator -configPath=./config -direction=up -packages=1,2,3.

Tip

The MibBulkMigrator also uses the -configPath directory to apply the existing MibLogConfig there, allowing its storage/viewing to be configured.

How to configure the migrations to be executed?

For this, we create a configuration file called MibBulkMigratorConfig.mibconfig. Through this configuration, it is possible to define everything needed for the execution of the migrations. Let's take a look at its structure:

<?xml version="1.0" encoding="UTF-8"?>
<config>
	<default>
		<nugetLocalPath></nugetLocalPath>
		<nugetUrl></nugetUrl>
		<mibMigratorVersion></mibMigratorVersion>
	</default>
	<migrationPackages>
		<package>
			<id></id>
			<name></name>
			<description></description>
			<nuget>
				<name></name>
				<url></url>
				<credentials>
					<username></username>
					<pass></pass>
				</credentials>
			</nuget>
			<mibMigratorVersion></mibMigratorVersion>
			<mibDatabaseConfig>
				<type></type>
				<server></server>
				<database></database>
				<username></username>
				<password></password>
				<port></port>
				<timeout></timeout>
			</mibDatabaseConfig>
			<migrations>
				<migration>
					<packageId></packageId>
					<packageVersion></packageVersion>
					<assembly></assembly>
					<up>
						<beforeSQL></beforeSQL>
						<target></target>
						<afterSQL></afterSQL>
					</up>
					<down>
						<beforeSQL></beforeSQL>
						<target></target>
						<afterSQL></afterSQL>
					</down>
				</migration>
			</migrations>
		</package>
	</migrationPackages>
</config>

Let's go through each configuration block:

Default

nugetLocalPath: Path where the MibBulkMigratorConfig.mibconfig configuration file should be located.
nugetUrl: NuGet URL to fetch the versions of MibMigrator.
mibMigratorVersion: The version of MibMigrator that should be used.

MigrationPackages

package: List of information about the packages to be executed.

Package

id: Package identifier, which can be used in the -packages option when calling the mibbulkmigrator command.
name: Identifier of the package.
disable Indicates whether the package should be considered in the execution.
description: Description of the package.
nuget: Specific NuGet details to be used for this package.
mibMigratorVersion: Specific version of MibMigrator to be used for this package.
mibDatabaseConfig: Configuration for database access details where the migrations should be applied.
migrations: List of migrations contained in the package.

Nuget

name: NuGet package name.
url: URL to access the NuGet repository.
credentials: Credentials to access the NuGet repository (username and pass).

MibDatabaseConfig

Follow the guidance in this section.

Migrations

List of migrations.

Migration

packageId: Package identifier.
packageVersion: Migration version, indicating which version of MibMigrator should be used.
assembly: Migration assembly file name.

Up / Down

beforeSQL: SQL script path that should be applied before the execution of the migration.
target: Target of the migration.
afterSQL: SQL script path that should be applied after the execution of the migration.

Tip

When the "up" command is executed, the Migration it is executed in the order they were arranged in the configuration file. When the "down" command is executed, the Migration it is executed in the reverse order of the configuration.