about_Rivet_Plugins

Explains the Rivet plug-in system

Description

Rivet plug-ins allow users to modify migration operations or perform other work before and after an operation is applied to a database. Examples include:

Validating that all tables/columns have descriptions.
Automatically adding created and last updated columns to each new table.
Validating that any raw SQL doesn't include a USE statement.
Preventing certain operations from being used, e.g. Rename-Column.
Customizing constraint and index names.

There are two plug-in points: before an operation is applied to a database and after an operation is applied to a database.

In order to cancel a migration, a plug-in must throw an exception. For example,

throw ('Operation is invalid: all tables are required to specify a description. Use the -Description parameter to document this table''s purpose.')

To enable plug-ins, you need to configure Rivet so it knows where to look for them. Set the plug-insRoot option to the directory path where you want to put your plug-ins. For example,

{
    "SqlServerName":  "example.com\Rivet",
    "DatabasesRoot":  "Databases",
    "PluginsRoot":  "Tools\\Rivet\\Plugins"
}

Paths in rivet.json files are relative to the rivet.json file. See about_Rivet_Configuration for more information.

Once you've defined your plug-ins directory, you create the plug-in scripts. To run code before an operation is applied to database, create a Start-MigrationOperation.ps1 script in your plug-ins directory. It should look like this:

function Start-MigrationOperation
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [Rivet.Migration]
        # The migration the operation is part of.
        $Migration,

        [Parameter(Mandatory=$true)]
        [Rivet.Operation]
        # The operation which is about to be applied.
        $Operation
    )

    Set-StrictMode -Version 'Latest'

    # Your plug-in logic goes here.
}

To run code after an operation is applied to a database, create a Complete-MigrationOperation.ps1 script in your plug-ins directory. It should look like this:

function Complete-MigrationOperation
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [Rivet.Migration]
        # The migration the operation is part of.
        $Migration,

        [Parameter(Mandatory=$true)]
        [Rivet.Operation]
        # The operation which was just applied.
        $Operation
    )

    Set-StrictMode -Version 'Latest'

    # Your plug-in logic goes here.
}

Rivet ships with some sample plug-ins. Look in the Extras directory.

Each plug-in should have two parameters: the first is a Rivet.Migration object representing the migration getting run. The second is a Rivet.Operation object representing the specific operation getting run. Each plug-in will get called for each operation in a migration. You'll get the same migration object for each operation in that migration.

Each operation in Rivet is represented by a unique C# object that you can modify. You can't remove operations from being run. Instead, throw an exception to reject the operation. You are allowed to run additional operations and/or return additional C# operation objects. See the sample plug-ins in the Extras directory that ships with Rivet.

about_Rivet_Plugins

Description

See Also