Getting started with River Pro

River Pro requires a few additional steps to get started beyond those of the main River package. This page describes configuring River Pro's private Go proxy, installing the Pro driver to source code, and how to run Pro migrations.

Quick start

With a River Pro secret obtained during the subscription process, add River Pro to an existing Go module:

export RIVER_PRO_SECRET=river_secret_...
export GOPROXY=https://proxy.golang.org,https://river:$RIVER_PRO_SECRET@riverqueue.com/goproxy,direct
export GONOSUMDB=riverqueue.com/riverpro,$GONOSUMDB

# install riverpro modules:
go get riverqueue.com/riverpro
go get riverqueue.com/riverpro/driver/riverpropgxv5

# install riverpro CLI:
go install riverqueue.com/riverpro/cmd/riverpro@latest

# the main River package is also required:
go get github.com/riverqueue/river

Assuming everything worked, Go will have updated the project's go.mod and go.sum files with new entries for River Pro. For more information on sustainably managing GOPROXY/GONOSUMDB environment variables in a Go project, or to use the riverpro modules in a CI environment, see Installing private Go modules.

Initializing a client

A River Pro client is initialized similar to a normal River Client, except with the use of the riverpro.NewClient constructor and the riverpropgxv5 driver instead of riverpgxv5:

import (
    ...

    "github.com/riverqueue/river"
    "riverqueue.com/riverpro"
    "riverqueue.com/riverpro/driver/riverpropgxv5"
)

riverClient, err := riverpro.NewClient(riverpropgxv5.New(dbPool), &riverpro.Config{
    Config: river.Config{
        Queues: map[string]river.QueueConfig{
            river.QueueDefault: {MaxWorkers: 100},
        },
        Workers: workers,
    }
})
if err != nil {
    // handle error
}

if err := riverClient.Start(ctx); err != nil {
    // handle error
}

Running Pro migrations

Most Pro features will require additional migrations. These are available through the alternate riverpro CLI containing all normal river CLI commands and functionality, but with additions specifically for use with Pro.

With 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 a Pro migration line according to the features you intend to use
riverpro migrate-up --database-url "$DATABASE_URL" --line sequence
riverpro migrate-up --database-url "$DATABASE_URL" --line workflow

Go package docs

River Pro's riverpro Go package has generated documentation hosted on this website. Docs are available for each released, along with the latest version always available at a fixed URL.