Skip to content

Pro migrations

Pro features often require additional migration lines to carry out tasks like adding additional indexes for Pro-specific features. Run migrations from the command line or through the Go, Ruby, and Rust migration APIs.

The pro migration line is required for most River Pro features. To onboard a new service, you can run all of the main migrations followed by the pro migration line. This order is recommended any time you’re automatically running migrations in a deployment.


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.

Inspecting and previewing migrations

Set DATABASE_URL to the target database. Inspect the migration history or preview pending changes before applying them. Apply main before previewing Pro migrations on a new database.

Terminal window
riverpro migrate-list --database-url "$DATABASE_URL" --line pro
riverpro migrate-up --database-url "$DATABASE_URL" --line pro --dry-run --show-sql

--dry-run leaves the database unchanged; --show-sql includes each migration’s SQL. Use --target-version N to migrate to a version and --max-steps N to limit the number of migrations.

Validating migrations

Validate both main and pro after migrating; see the getting-started commands. Validation checks the recorded versions without modifying the database, and does not compare database object definitions. A successful check exits with status 0; pending migrations or errors return a nonzero status.

The Rust CLI also accepts validate --target-version N to check through a specific version. Its validation ignores unknown newer versions, so a successful check does not replace selecting a CLI version compatible with the application.

Rolling back

If reverting both lines, revert Pro before main. Down migrations can remove tables, job data, and stored workflow state, so inspect the SQL and release notes before applying them. Rolling back application code does not by itself require rolling back the schema.

Preview the SQL, then revert one Pro migration:

Terminal window
riverpro migrate-down --database-url "$DATABASE_URL" --line pro --dry-run --show-sql
riverpro migrate-down --database-url "$DATABASE_URL" --line pro

Down migrations default to one step. Use --max-steps N or --target-version N to select a different boundary.

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 migrations from code

Like with the main River project, migrations are runnable from Go code. Make sure to use the riverpropgxv5 driver (or riverprosqlite) 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.