Updating River

Update related River packages together and review release notes for migrations or API changes. In mixed-language deployments, migrate only to a schema supported by all still-running clients.

To keep third party dependencies as self-contained as possible, River is distributed as a set of interrelated Go Modules. Normally when fetching the top level github.com/riverqueue/river Go will resolve new versions of other modules as it needs to, but especially when working with new releases, it may accidentally find incompatible versions.

For best results, it’s recommend that all River-related modules be updated simultaneously using a single invocation of go get:

RIVER_VERSION=latest;

go get -u github.com/riverqueue/river@$RIVER_VERSION \
        github.com/riverqueue/river/cmd/river@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver/riverdatabasesql@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver/riverpgxv5@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver/riversqlite@$RIVER_VERSION \
        github.com/riverqueue/river/rivershared@$RIVER_VERSION \
        github.com/riverqueue/river/rivertype@$RIVER_VERSION && \
    go mod tidy

Chaining go mod tidy makes sure that any drivers that weren’t in use by the project are stripped back out again.

Update the pinned com.riverqueue:river version in your Maven or Gradle configuration, keeping River’s Maven repository configured. Install the matching CLI and its runtime dependencies using the migration setup instructions. Review the Java changelog and run migrations before starting updated workers.

Update the core gem and the driver gems in the same Bundler operation:

bundle update riverqueue riverqueue-sequel

Substitute riverqueue-activerecord when using Active Record. Commit the updated lockfile and run migrations before starting the updated workers.

Update River’s crates together within the version requirements in Cargo.toml:

cargo update -p riverqueue

For a new version outside those requirements, update Cargo.toml first. Keep optional riverqueue-test and riverqueue-migrate dependencies compatible with the core crate. Update a separately installed CLI with cargo install riverqueue-cli --locked.

Update the River packages your application uses together:

npm install riverqueue@latest @riverqueue/driver-pg@latest @riverqueue/migrate@latest
npm install --save-dev @riverqueue/cli@latest @riverqueue/test@latest

Include other River drivers or extensions you use and keep their versions aligned. Commit the updated lockfile.

River Pro

If using River Pro, include Pro modules along with the standard ones:

RIVER_VERSION=latest;
RIVER_PRO_VERSION=latest;

go get -u github.com/riverqueue/river@$RIVER_VERSION \
        github.com/riverqueue/river/cmd/river@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver/riverdatabasesql@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver/riverpgxv5@$RIVER_VERSION \
        github.com/riverqueue/river/riverdriver/riversqlite@$RIVER_VERSION \
        github.com/riverqueue/river/rivershared@$RIVER_VERSION \
        github.com/riverqueue/river/rivertype@$RIVER_VERSION \
        riverqueue.com/riverpro@$RIVER_PRO_VERSION \
        riverqueue.com/riverpro/driver@$RIVER_PRO_VERSION \
        riverqueue.com/riverpro/driver/riverprodatabasesql@$RIVER_PRO_VERSION \
        riverqueue.com/riverpro/driver/riverpropgxv5@$RIVER_PRO_VERSION && \
    go mod tidy

Keep River’s private source and Bundler credentials configured, then update the Pro gem, core gem, and driver together:

bundle update riverqueue-pro riverqueue riverqueue-activerecord
bundle exec river migrate-up --database-url "$DATABASE_URL"
bundle exec river migrate-up --database-url "$DATABASE_URL" --line pro

Substitute riverqueue-sequel if that’s your driver. Bundler resolves the Pro gem’s core version requirement. Commit the updated lockfile and run migrations before starting updated workers. Ruby gem versions are independent of Go module versions.

Update riverqueue and riverqueue-pro as the compatible version pair, keeping Pro’s client, migrator, test helpers, and CLI at the same Pro version. After updating Cargo.toml, refresh and verify the lockfile:

cargo update -p riverqueue -p riverqueue-pro
cargo build --locked
cargo test --locked

Build or reinstall the Pro CLI at the new Pro version. Its installation is separate from the application’s lockfile. Apply migrations before starting upgraded workers:

riverqueue migrate-up --database-url "$DATABASE_URL" --line main
riverqueue migrate-up --database-url "$DATABASE_URL" --line pro

Commit Cargo.toml and Cargo.lock together. Rust versions are independent of Go and Ruby versions.