v0.27.0

Added

• Periodic jobs with IDs may now be removed by ID using the new PeriodicJobBundle.RemoveByID and PeriodicJobBundle.RemoveManyByID. PR #1071.

Changed

• Decrease serviceutil.MaxAttemptsBeforeResetDefault from 10 to 7, lowering the effective limit on most internal exponential backoffs from ~512 seconds to 64 seconds. Further lowered the leader elector's keep leadership backoff interval to cap out at 4 seconds since leadership without a successful heartbeat will be lost soon after that anyway. PR #1079.

Fixed

• Fix snoozed events emitted from rivertest.Worker when snooze duration is zero seconds. PR #1057.
• Rollbacks now use an uncancelled context so as to not leave transactions in an ambiguous state if a transaction in them fails due to context cancellation. PR #1062.
• Removing periodic jobs with IDs assigned also remove them from ID map. PR #1070.
• Clear periodic jobs also fully clears all those assigned with an ID. PR #1083.
• river:"unique" annotations on substructs within JobArgs structs are now factored into uniqueness ByArgs calculations. PR #1076.
• Stop subservices and embedded baseservice.Service on error in the event of a periodic job enqueuer start error. PR #1081.

v0.26.0

⚠️ Internal APIs used for communication between River and River Pro have changed. If using River Pro, make sure to update River and River Pro to latest at the same time to get compatible versions. River v0.26.0 is compatible with River Pro v0.19.0.

Added

• The job rescuer now sets river:rescue_count with an integer count of how many times the job has been rescued by the JobRescuer maintenance process when it's considered stuck. PR #1047.

Changed

• Errors returned from job workers are now logged in full using a slog.Any attribute. Previously, only their error text was logged. PR #1051.

Fixed

• Set updated_at when invoking pilot PeriodicJobUpsert. PR #1045.

v0.25.0

⚠️ Internal APIs used for communication between River and River Pro have changed. If using River Pro, make sure to update River and River Pro to latest at the same time to get compatible versions. River v0.25.0 is compatible with River Pro v0.18.0.

Changed

• Set minimum Go version to Go 1.24. PR #1032.
• Breaking change: Client.JobDeleteMany now requires the use of JobDeleteManyParams.UnsafeAll to delete all jobs without a filter applied. This is a safety feature to make it more difficult to accidentally delete all non-running jobs. This is a minor breaking change, but on a fairly new feature that's not likely to be used on purpose by very many people yet. PR #1033.

Fixed

• Don't double log fetch errors. PR #1025.
• When snoozing a job with zero duration so that it's retried immediately, subscription events no longer appear incorrectly with a kind of rivertype.EventKindJobFailed. Instead they're assigned rivertype.EventKindJobSnoozed just like they would have with a non-zero snooze duration. PR #1037.

v0.24.0

⚠️ Version 0.24.0 has a breaking change in HookWorkEnd.WorkEnd in that a new JobRow parameter has been added to the function's signature. Any intergration defining a custom HookWorkEnd hook should update its implementation so the hook continues to be called correctly.

⚠️ Internal APIs used for communication between River and River Pro have changed. If using River Pro, make sure to update River and River Pro to latest at the same time to get compatible versions. River v0.24.0 is compatible with River Pro v0.16.0.

Added

• The project now tests against libSQL, a popular SQLite fork. It's used through the same riversqlite driver that SQLite uses. PR #957
• Added JobDeleteMany operations that remove many jobs in a single operation according to input criteria. PR #962
• Added Client.Schema() method to return a client's configured schema. PR #983.
• Integrated riverui queries into the driver system to pave the way for multi-driver UI support. PR #983.
• Added QueueConfig level FetchCooldown and FetchPollInterval settings to enable queue-specific job fetch intervals. For example, a queue of high-priority jobs could be checked more often to improve responsiveness, while one with slow or time-insensitive tasks could be checked infrequently to reduce database load. PR #994.

Changed

• Remove unecessary transactions where a single database operation will do. This reduces the number of subtransactions created which can be an operational benefit it many cases. PR #950
• Bring all driver tests into separate package so they don't leak dependencies. This removes dependencies from the top level river package that most River installations won't need, thereby reducing the transitive dependency load of most River installations. PR #955.
• The reindexer maintenance service now reindexes all river_job indexes, including its primary key. This is expected to help in situations where the jobs table has in the past expanded to a very large size (which makes most indexes larger), is now a much more modest size, but has left the indexes in their expanded state. PR #963.
• The River CLI now accepts a --target-version of 0 with river migrate-down to run all down migrations and remove all River tables (previously, -1 was used for this; -1 still works, but now 0 also works). PR #966.
• Breaking change: The HookWorkEnd interface's WorkEnd function now receives a JobRow parameter in addition to the error it received before. Having a JobRow to work with is fairly crucial to most functionality that a hook would implement, and its previous omission was entirely an error. PR #970.
• Add maximum bound to each job's attempted_by array so that in degenerate cases where a job is run many, many times (say it's snoozed hundreds of times), it doesn't grow to unlimited bounds. PR #974.
• A logger passed in via river.Config now overrides the default test-based logger when using rivertest.NewWorker. PR #980.
• Cleaner retention periods (CancelledJobRetentionPeriod, CompletedJobRetentionPeriod, DiscardedJobRetentionPeriod) can be configured to -1 to disable them so that the corresponding type of job is retained indefinitely. PR #990.
• Jobs inserted from periodic jobs with IDs now have metadata river:periodic_job_id set so they can be traced back to the periodic job that inserted them. PR #992.
• The unused function WorkerDefaults.Hooks has been removed. This is technically a breaking change, but this function was a vestigal refactoring artifact that was never used by anything, so in practice it shouldn't be breaking. PR #997.
• Periodic job records are upserted immediately through a pilot when a client is started rather than the first time their associated job would run. This doesn't mean they're run immediately (they'll only run if RunOnStart is enabled), but rather just tracked immediately. PR #998.
• The job scheduler still schedules jobs in batches of up to 10,000, but when it encounters a series of consecutive timeouts it assumes that the database is in a degraded state and switches to doing work in a smaller batch size of 1,000 jobs. PR #1013.
• Other maintenance services including the job cleaner, job rescuer, and queue cleaner also prefer a batch size of 10,000, but will fall back to smaller batches of 1,000 on consecutive database timeouts. PR #1016.

Fixed

• Cleanly error on invalid schema names in Config.Schema. PR #952.
• Jobs rescued by JobRescuer no longer have their trace set to "TODO". This becomes an empty string instead. PR #1010.

v0.23.1

This includes a minor CLI bugfix for riverpro and no other changes, see the v0.23.0 notes for major changes.

Fixed

• Fixed a riverpro CLI integration point broken in v0.23.0. PR #945

v0.23.0

⚠️ Internal APIs used for communication between River and River Pro have changed. If using River Pro, make sure to update River and River Pro to latest at the same time to get compatible versions. River v0.23.0 is compatible with River Pro v0.15.0.

Terminal UI: @almottier wrote a very cool terminal UI for River featuring real-time job monitoring with automatic refresh, job filtering, a job details view providing detailed information (plus look up by ID in the UI or by command line argument), and job actions like retry and cancellation. And as good as all that might sound, go take a look because it's even better in person.

Added

• Preliminary River driver for SQLite (riverdriver/riversqlite). This driver seems to produce good results as judged by the test suite, but so far has minimal real world vetting. Try it and let us know how it works out. PR #870.
• CLI river migrate-get now takes a --schema option to inject a custom schema into dumped migrations and schema comments are hidden if --schema option isn't provided. PR #903.
• Added riverlog.NewMiddlewareCustomContext that makes the use of riverlog job-persisted logging possible with non-slog loggers. PR #919.
• Added RequireInsertedOpts.Schema, allowing an explicit schema to be set when asserting on job inserts with rivertest. PR #926.
• When using a driver that doesn't support listen/notify, producers within same process are notified immediately of new job inserts and queue changes (e.g. pause/resume) without having to poll when non-transactional variants are used (i.e. Insert instead of InsertTx). PR #928.
• Added JobListParams.Where, which provides an escape hatch for job listing that runs arbitrary SQL with named parameters. PR #933.

Changed

• Optimized the job completer's query JobSetStateIfRunningMany, resulting in an approximately 15% reduction in its duration when completing 2000 jobs, and around a 15-20% increase in riverbench throughput. PR #904.
• TimeStub has been removed from the rivertest package. Its original inclusion was entirely accidentally and it should be considered entirely an internal API. PR #912.
• When storing job-persisted logging with riverlog, if a work run's logging was completely empty, no metadata value is stored at all (previously, an empty value was stored). PR #919.
• Changed the internal integration APIs for River Pro. River Pro users must upgrade both libraries as part of this update. PR #929.

Fixed

• Resuming an already unpaused queue is now fully an no-op, and won't touch the row's updated_at like it (unintentionally) did before. PR #870.
• Suppress an error log line from the producer that may occur on normal shutdown when operating in poll-only mode. PR #896.
• Added missing help documentation for CLI command river migrate-list. PR #903.
• Correct handling an explicit schema in the reindexer maintenance service. PR #916.
• Return specific explanatory error when attempting to use JobListParams.Metadata with JobListTx on SQLite. PR #924.
• The reindexer now skips work if artifacts from a failed reindex are present under the assumption that if they are, a new reindex build is likely to fail again. Context cancel timeout is increased from 15 seconds to 1 minute, allowing more time for reindexes to finish. Timeout becomes configurable with Config.ReindexerTimeout. PR #935.
• Accessing Client.PeriodicJobs() on an insert-only client now panics with a more helpful explanatory error message rather than an unhelpful nil pointer panic. PR #938.
• Return an error when adding a new queue at runtime via the QueueBundle if that queue was already added. PR #929.

v0.22.0

Added

• A new JobArgsWithKindAliases interface lets job args implement KindAliases to register a second kind that their worker will respond to. This provides a way to safely rename job kinds even with jobs using the original kind already in the database. PR #880.

Changed

• Job kinds must comply to a format of \A[\w][\w\-\[\]<>\/.·:+]+\z, mainly in an attempt to eliminate commas and spaces to make format more predictable for an upcoming search UI. This check can be disabled for now using Config.SkipJobKindValidation, but this option will likely be removed in a future version of River. The new JobArgsWithKindAliases interface (see above) can be used to rename non-compliant kinds. PR #879.

Fixed

• The riverdatabasesql now fully supports raw connections through lib/pq rather than just database/sql through Pgx. We don't recommend the use of lib/pq as it's an unmaintained project, but this change should help with compatibility for older projects. PR #883.

v0.21.0

⚠️ Internal APIs used for communication between River and River Pro have changed. If using River Pro, make sure to update River and River Pro to latest at the same time to get compatible versions.

Added

• Added river/riverlog containing middleware that injects a context logger to workers that collates log output and persists it with job metadata. This is paired with a River UI enhancement that shows logs in the UI. PR #844.
• Added JobInsertMiddlewareFunc and WorkerMiddlewareFunc to easily implement middleware with a function instead of a struct. PR #844.
• Added Config.Schema which lets a non-default schema be injected explicitly into a River client that'll be used for all database operations. This may be particularly useful for proxies like PgBouncer that may not respect a schema configured in search_path. PR #848.
• Added rivertype.HookWorkEnd hook interface that runs after a job has been worked. PR #863.
• Added support for filtering jobs by a list of job IDs and by priorities in JobList and JobListParams. For more flexible job listing. PR #871.

Changed

• Client no longer returns an error if stopped before startup could complete (previously, it returned the unexported ErrShutdown). PR #841.

Fixed

• A queue unpausing triggers an immediate fetch so that available jobs in the paused queue may be started faster than before. PR #854.

v0.20.2

Added

• Added QueueUpdateTx API so there's a transactional variant of the QueueUpdate API from PR #834. PR #838.

v0.20.1

Fixed

• Corrected the serialization of queue control event payloads emitted by QueueUpdate. PR #834.