Database drivers

River makes use of drivers to insulate itself from third party packages, enabling future use of other database packages or new major versions. Currently the only supported driver is riverpgxv5.

The River Client takes a generic TTx type parameter representing the type of the transaction in use for functions like InsertTx and InsertManyTx. TTx is derived from the client's driver, an agnostic interface to a third party package that provides protocol access to Postgres.

Most of the time, the only time code references a database driver is when it's initializing a River client. NewClient takes a driver as its first parameter, and the driver wraps a database pool:

import "github.com/riverqueue/river"
import "github.com/riverqueue/river/riverdriver/riverpgxv5"

...

dbPool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
if err != nil {
    panic(err)
}
defer dbPool.Close()

riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{
    ...
})
if err != nil {
    panic(err)
}

See the InsertAndWork example for complete code.

Currently River's only supported driver is riverpgxv5, a wrapper around the excellent pgx v5 package, which is performant, feature complete, production hardened, and well maintained.

Some rationale for why other drivers aren't currently supported:

• Go's built in database/sql package is broadly considered to be misdesigned, and is too generic to provide access to important Postgres features.

• Older Postgres packages in the Go ecosystem like lib/pq are in maintenance mode and haven't been recommended for new projects for a long time.

• Pgx had an older stable v4 major version which probably garnered widespread use, but v5 has been released for quite some time, and existing v4 users can reasonably be expected to upgrade to v5 in the near term.

With that said, River is a new project and we're open to feedback from the Go community on which packages should be supported. If you feel that there's good reason for another driver to be added, open an issue on GitHub and we'll evaluate it.