Skip to content
River Docs

Pro migrations

Pro features often require additional migration lines to carry out tasks like adding additional indexes for Pro-specific features. This page describes how to install the River Pro CLI, using it continuous integration environments like GitHub Actions, and invoking migrations from Go code.

Each specific Pro feature may or may not require a migration line, and migration lines need only be run for Pro features that a project intends to use. For example, the workflows migration line should only be raised when using workflows.

Installing the River Pro CLI

River Pro distributes an alternate riverpro CLI which contains all the normal river CLI commands and functionality, but with additions specifically for use with Pro. Configure your environment to install River Pro (including GOPROXY/GONOSUMDB) and install the CLI with:

Terminal window
go install riverqueue.com/riverpro/cmd/riverpro@latest

With the DATABASE_URL of a target database (looks like postgres://host:5432/db), migrate up:

Terminal window
# first, install the standard River migrations:
riverpro migrate-up --database-url "$DATABASE_URL"


# then add the pro migration line:
riverpro migrate-up --database-url "$DATABASE_URL" --line pro

The riverpro CLI must be used for Pro migrations

The main River project distributes its own river CLI to run migrations, but when running Pro migration lines, the riverpro CLI must be used instead. The non-Pro CLI doesn't know about them.

See also installing in CI and build environments.

Outputting SQL for use in other frameworks

As with non-Pro migrations, the riverpro migrate-get command can be used to output the SQL for a given migration line and version:

Terminal window
riverpro migrate-get --line pro --version 1 --up > river_pro_1.up.sql
riverpro migrate-get --line pro --version 1 --down > river_pro_1.down.sql

Running Pro migration lines from Go

Like with the main River project, migrations are runnable from Go code. Make sure to use the riverpropgxv5 driver instead of riverpgxv5, and specify an optional Line property to target a Pro line:

migrator := rivermigrate.New(riverpropgxv5.New(dbPool), &rivermigrate.Config{
    Line: "pro",
})


res, err := migrator.MigrateTx(ctx, tx, rivermigrate.DirectionUp, &rivermigrate.MigrateOpts{})
if err != nil {
    // handle error
}

Leaving Line empty will default to the main River migration line.

Deprecated migration lines

Earlier versions of River Pro (v0.10.0 and earlier) shipped with feature-specific migration lines named sequence and workflow. These are now deprecated and will be removed in a future version of River Pro.

As noted in the changelog, the new unified pro migration line contains all the functionality of the deprecated sequence and workflow migration lines. It is also configured to run idempotently to simplify the transition, meaning it will bring the database up to the latest Pro schema even if some or all of the deprecated lines have already been run.