riverqueue / river

Fast and reliable background jobs in Go
https://riverqueue.com
Mozilla Public License 2.0
3.22k stars 86 forks source link

Docs should make insert-only Client mode clearer #371

Closed ewhauser closed 2 months ago

ewhauser commented 3 months ago

When creating a new River client, the client forces you to supply queues and workers. Specifying this configuration does things like 1) run leader election 2) start the reindexer 3) start polling for jobs 4) etc. There are a couple reason the client should support insert only mode:

1) There are many instances where a service/job will just be inserting jobs into the queue vs. also running workers 2) If you are testing code that is only doing inserts

bgentry commented 3 months ago

Hi @ewhauser, you can in fact already run an insert-only Client—you just need to omit specifying the Queues field in the Config:

type Config struct {
    // ...

    // Queues is a list of queue names for this client to operate on along with
    // configuration for the queue like the maximum number of workers to run for
    // each queue.
    //
    // This field may be omitted for a program that's only queueing jobs rather
    // than working them. If it's specified, then Workers must also be given.
    Queues map[string][QueueConfig]

    // ...
}

I don't think this is obvious or discoverable enough atm though, so I'll repurpose this issue to help us track the doc fixes. This is a common enough use case that we probably want something dedicated to this in the godocs (maybe an executable code example as well) and also likely a section on one of the docs pages.

Pinging @brandur to see if he has thoughts on the most obvious place for this to live.

ewhauser commented 3 months ago

I'm getting this with 0.6.1:

client, err := river.NewClient[pgx.Tx](riverpgxv5.New(pool),  &river.Config{})
require.NoError(t, err)
client Queues and Workers must be configured for a client to start working
bgentry commented 3 months ago

@ewhauser it seems you're calling Start given the error message? Clients only need to be started if they're meant to be executing jobs, not for insert-only.

ewhauser commented 3 months ago

Ah, yes. Sorry. Thank you!

brandur commented 3 months ago

Yes I agree the docs are too hard to find right now. Opened #375.