diff --git a/client.go b/client.go index 13d70866..e0749bb5 100644 --- a/client.go +++ b/client.go @@ -48,6 +48,12 @@ const ( ) // Config is the configuration for a Client. +// +// Both Queues and Workers are required for a client to work jobs, but an +// insert-only client can be initialized by omitting Queues, and not calling +// Start for the client. Workers can also be omitted, but it's better to include +// it so River can check that inserted job kinds have a worker that can run +// them. type Config struct { // AdvisoryLockPrefix is a configurable 32-bit prefix that River will use // when generating any key to acquire a Postgres advisory lock. All advisory diff --git a/doc.go b/doc.go index b63fde26..4b5373a7 100644 --- a/doc.go +++ b/doc.go @@ -64,7 +64,6 @@ goroutines at a time: }, Workers: workers, }) - if err != nil { panic(err) } @@ -74,6 +73,22 @@ goroutines at a time: panic(err) } +## Insert-only clients + +It's often desirable to have a client that'll be used for inserting jobs, but +not working them. This is possible by omitting the `Queues` configuration, and +skipping the call to `Start`: + + riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{ + Workers: workers, + }) + if err != nil { + panic(err) + } + +`Workers` can also be omitted, but it's better to include it so River can check +that inserted job kinds have a worker that can run them. + ## Stopping The client should also be stopped on program shutdown: @@ -112,6 +127,9 @@ See the [`InsertAndWork` example] for complete code. - [Error and panic handling]. + - [Multiple queues] to better guarantee job throughput, worker availability, + and isolation between components. + - [Periodic and cron jobs]. - [Scheduled jobs] that run automatically at their scheduled time in the @@ -122,6 +140,8 @@ See the [`InsertAndWork` example] for complete code. - [Subscriptions] to queue activity and statistics, providing easy hooks for telemetry like logging and metrics. + - [Test helpers] to verify that jobs are inserted as expected. + - [Transactional job completion] to guarantee job completion commits with other changes in a transaction. diff --git a/docs/README.md b/docs/README.md index 58a7ea6b..f0c152d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -71,7 +71,6 @@ riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{ }, Workers: workers, }) - if err != nil { panic(err) } @@ -82,6 +81,22 @@ if err := riverClient.Start(ctx); err != nil { } ``` +## Insert-only clients + +It's often desirable to have a client that'll be used for inserting jobs, but +not working them. This is possible by omitting the `Queues` configuration, and +skipping the call to `Start`: + + riverClient, err := river.NewClient(riverpgxv5.New(dbPool), &river.Config{ + Workers: workers, + }) + if err != nil { + panic(err) + } + +`Workers` can also be omitted, but it's better to include it so River can check +that inserted job kinds have a worker that can run them. + ### Stopping The client should also be stopped on program shutdown: