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:
go install riverqueue.com/riverpro/cmd/riverpro@latestWith the DATABASE_URL of a target database (looks like postgres://host:5432/db), migrate up:
# 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 proThe 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.
Install riverqueue-pro and a Ruby driver in your bundle using the getting-started instructions:
bundle installThe core gem supplies river; it loads the private Pro migration files when passed --line pro:
bundle exec river migrate-up --database-url "$DATABASE_URL"bundle exec river migrate-up --database-url "$DATABASE_URL" --line proThe CLI auto-detects the available driver, preferring Sequel when both drivers are installed. Use a Postgres URL, a Sequel sqlite: URL, or an ActiveRecord sqlite3: URL. Pass --schema jobs for an existing Postgres schema. The riverqueue-pro gem must be installed for the Pro line to be available.
See private package installation for CI credentials. Run one migration process at a time across all languages; Ruby’s migration locks do not coordinate with Go’s runner.
The riverqueue-pro-cli package installs a riverqueue executable containing both main and Pro migrations. Follow the getting-started guide for package installation and private-registry configuration.
riverqueue migrate-up --database-url "$DATABASE_URL" --line mainriverqueue migrate-up --database-url "$DATABASE_URL" --line proriverqueue validate --database-url "$DATABASE_URL" --line mainriverqueue validate --database-url "$DATABASE_URL" --line proBoth Postgres and SQLite are included by default. Use the same --schema NAME for both lines when migrating an alternate Postgres schema. The compiled CLI runs without Cargo; see deployment instructions.
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.
riverpro migrate-list --database-url "$DATABASE_URL" --line proriverpro 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.
bundle exec river migrate-status --database-url "$DATABASE_URL" --line probundle exec river migrate-up --database-url "$DATABASE_URL" --line pro --dry-runmigrate-status reports applied and pending versions. The dry run prints planned versions without applying them. Use migrate-get below to inspect their SQL. Use --target N to select a target version or --steps N to limit the number of migrations.
riverqueue migrate-list --database-url "$DATABASE_URL" --line proriverqueue migrate-up --database-url "$DATABASE_URL" --line pro --dry-run --show-sqlThe list marks the latest applied version with *. --dry-run prints the selected versions without applying them; --show-sql includes their SQL and also works when applying migrations. Use --target-version N to select a target version and --max-steps N to bound the number of migrations.
Each migration and its history record commit in one transaction, so a retry after failure resumes from the remaining migrations. Explicit --database-url URL overrides DATABASE_URL; an empty explicit value is an error. Supported URL schemes are postgres://, postgresql://, and sqlite:.
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:
riverpro migrate-down --database-url "$DATABASE_URL" --line pro --dry-run --show-sqlriverpro migrate-down --database-url "$DATABASE_URL" --line proDown migrations default to one step. Use --max-steps N or --target-version N to select a different boundary.
Preview the planned versions, then confirm the rollback:
bundle exec river migrate-down --database-url "$DATABASE_URL" --line pro --dry-runbundle exec river migrate-down --database-url "$DATABASE_URL" --line pro --yesDown migrations default to one step and require --yes to apply. Use --steps N or --target N to select a different boundary; --target 0 reverts the entire line. Inspect the SQL with migrate-get --line pro --version N --down before applying it.
Preview the SQL, then revert one Pro migration:
riverqueue migrate-down --database-url "$DATABASE_URL" --line pro --dry-run --show-sqlriverqueue migrate-down --database-url "$DATABASE_URL" --line proDown migrations default to one step. --target-version -1 reverts every migration in the selected line and can delete its tables and data.
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:
riverpro migrate-get --line pro --version 1 --up > river_pro_1.up.sqlriverpro migrate-get --line pro --version 1 --down > river_pro_1.down.sqlWith riverqueue-pro installed, use the core command with --line pro to export SQL without connecting to a database or installing a River driver gem:
bundle exec river migrate-get --line pro --version 1 --up > river_pro_1.up.sqlbundle exec river migrate-get --line pro --version 1 --down > river_pro_1.down.sqlThe command supports the same version selection, exclusions, and schema substitution as the main migration line. Export defaults to Postgres; pass --database-url sqlite:// (or sqlite3://) for SQLite SQL. Preserve version boundaries, applying main before Pro and reversing Pro before main.
Use migrate-get to export embedded SQL without connecting to a database:
riverqueue migrate-get --line pro --version 1 --up > river_pro_1.up.sqlriverqueue migrate-get --line pro --version 1 --down > river_pro_1.down.sqlChoose either --all or --version, and either --up or --down. --all orders versions ascending for up and descending for down; explicit versions keep the supplied order. --version and --exclude-version accept comma-separated values and may be repeated.
Export defaults to Postgres and ignores DATABASE_URL. Pass --schema jobs to render Postgres schema references, or --database-url sqlite:// for SQLite SQL:
riverqueue migrate-get --line pro --all --up --schema jobs > river_pro.up.sqlriverqueue migrate-get --line pro --all --up --database-url sqlite:// > river_pro.sqlite.up.sqlFor export, --schema substitutes a literal SQL prefix on either backend. Include SQL quoting when needed, such as --schema '"JobsArchive"'. Commands that apply migrations instead accept an unquoted Postgres schema name and quote it themselves.
Each migration starts with a SQL comment identifying its line, version, and direction. Exported SQL does not add the migration history records managed by migrate-up. Preserve version boundaries and one transaction per migration, applying main before Pro and reversing Pro before main.
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.
Use the ordinary driver with River::Migrator for the main line and River::Pro::Migrator for Pro:
require "riverqueue-pro"
River::Migrator.new(driver).migrateRiver::Pro::Migrator.new(driver).migrateBoth accept schema: for Postgres. Each migration version commits in its own transaction; do not wrap the migrator in an application transaction. migrate(dry_run: true) returns the plan without applying it, and status reports applied and pending versions.
All River languages share the canonical migration SQL and river_migration history, so migrations already applied by one client do not need to be run again by another.
Apply main before Pro, using the same pool:
riverqueue::migrate::PostgresMigrator::new(pool.clone()) .migrate_up() .await?;riverqueue_pro::migrate::PostgresMigrator::new(pool.clone()) .migrate_up() .await?;The Pro migrator defaults to the pro line. For an alternate Postgres schema, call with_schema on both migrators with the same SchemaName. For SQLite, use SqliteMigrator from each crate. See SQLite setup.
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.
The Ruby gem uses the unified pro migration line. It does not expose the legacy feature-specific sequence and workflow lines. When adding Ruby to an older Go deployment, update the database to the unified Pro schema before starting Ruby clients.
New installations use main and pro only. riverqueue migrate-up --line pro also consolidates databases previously migrated through sequence and workflow, preserving their tables and data while replacing their migration records. The deprecated lines remain available for compatibility with older installations.