v0.45.0

Changed

• Upgrade supported Go versions to 1.26 and 1.27. PR #1356.

Fixed

• Fixed periodic jobs advancing their durable next run time when job insertion fails. PR #1359.
• Improved SQLite queue count performance on large job tables by limiting counts to available and running jobs so the existing state and queue index can be used. PR #1360.

v0.44.1

Fixed

• SQLite job completion, rescue, and full-update paths now serialize timestamps using River's standard millisecond format instead of relying on database driver serialization, preventing inconsistent timestamp representations from being persisted. PR #1353
• SQLite drivers now return a non-nil empty JobRow.Errors slice for jobs without errors, matching the behavior of PostgreSQL drivers and ensuring the field serializes to [] instead of null. PR #1354.

v0.44.0

Added

• Added EventKindJobInterrupted, emitted when a running job is interrupted because its client is shutting down, the job was cancelled, and has been made immediately available to be worked again. PR #1290.

Changed

• Jobs that didn't finish in time organically while a client was stopping and had to have their context cancelled no longer have this cancellation counted as an error. attempt is reset to the number it was before the job started working, errors is left unchanged, and state is made available so jobs are eligible to be retried immediately. PR #1290

Fixed

• Write timestamps in SQLite to always include three digits after the second like .000. Previously, they may have been truncated down to just .0 in the case of trailing zeroes. PR #1349
• Job completion events now reflect the job's persisted outcome when it differs from the transition requested by the worker. For example, a job completed with JobCompleteTx before its worker returns an error emits job_completed, and a remotely cancelled job whose worker errors or snoozes emits job_cancelled. Applications subscribed only to job_failed or job_snoozed should note that these events may instead be delivered to job_completed or job_cancelled subscribers. PR #1350

v0.43.0

Added

• Added JobListParams.TagsAll and JobListParams.TagsAny for filtering jobs that match every or any exact tag, respectively. PR #1339.

Fixed

• testsignal no longer imports riversharedtest, so testify, go-spew, goleak, and yaml are no longer linked into production binaries that use River. WaitTimeout moved to rivershared/util/testutil, with riversharedtest.WaitTimeout kept as a wrapper around it. PR #1342.

v0.42.0

Added

• Added JobArgsWithPlugins for installing plugins that apply only to a specific job type. PR #1337.

v0.41.1

Fixed

• Fixed JobRescuer incorrectly rescuing jobs whose worker timeout of zero inherits a client-level Config.JobTimeout of -1 (no timeout). PR #1331.

v0.41.0

Added

• Added rivertype.HookMetricEmit for receiving metrics emitted by River. Initial metrics report the duration of successful job fetches with JobGetAvailableDurationMetric and the number of jobs fetched with JobGetAvailableCountMetric. PR #1285.
• The riversqlite driver is now tested against Turso, an in-process SQLite-compatible database written in Rust. PR #1311.

Changed

• Added Config.Plugins for extensions that should be installed as both hooks and middleware. Config.Hooks and Config.Middleware remain available for hook-only and middleware-only registration. PR #1284.
• Reduce producer keep alive interval from 1 minute to 30 seconds. PR #1319.

Fixed

• Guard against empty job slice returned by JobSetStateIfRunningMany when a job has been deleted mid-run. PR #1308.
• Fixed JobRescuer pagination so a full batch of running jobs with disabled or longer worker-specific timeouts can't prevent later stuck jobs from being rescued. PR #1318.
• If a job fails to unmarshal from JSON during job rescue or job execution, back off using the retry schedule and eventually discard it, similar to any other error that might occur. PR #1324.
• Fixed JobListOrderByFinalizedAt validation so finalized states are accepted while non-finalized states are rejected. PR #1327.

v0.40.0

⚠️ Version 0.40.0 contains a new database migration, version 7, that rolls up some database cleanups and a few SQLite features:

• Drop tables river_client and river_client_queue. These were added prospectively, but in the end were never used for anything. PR #1115.
• Add a default value of 25 to river_job.max_attempts. Go code was previously injecting a max value, so this has no functional effect on existing behavior. PR #1115.
• Add a default value of CURRENT_TIMESTAMP to river_queue.updated_at. Go code was previously injecting the current time, so this has no functional effect on existing behavior. PR #1115.
• SQLite only: Convert json columns to jsonb. PR #1224.
• SQLite only: Add pseudo listen/notify mechanism in a new river_notification table. PR #1275.

For SQLite, running River apps must be stopped briefly while the migration is run and their code upgrade to 0.40.0 so they start reading and inserting new values in jsonb instead of json.

See documentation on running River migrations. If migrating with the CLI, make sure to update it to its latest version:

go install github.com/riverqueue/river/cmd/river@latest
river migrate-up --database-url "$DATABASE_URL"

If not using River's internal migration system, the raw SQL can alternatively be dumped with (or change --database-url to a Postgres URI for Postgres versions):

go install github.com/riverqueue/river/cmd/river@latest
river migrate-get --database-url sqlite:// --version 7 --up > river7.up.sql
river migrate-get --database-url sqlite:// --version 7 --down > river7.down.sql

Added

• SQLite picks up a new river_notification table that allows River to provide listen/notify-like functionality despite these functions not being supported outside of Postgres. PR #1275.
• Added JobStuckHandler, giving clients a hook to handle "stuck" jobs (i.e. ones which are passed timeout and haven't responded to context cancellation) and potentially open a new worker slot if so desired. PR #1291.

Changed

• Convert SQLite JSON columns to JSONB (including migration). PR #1224.
• Change SQLite driver operations over to use bulk inserts where possible now that sqlc has better support for json_each. PR #1276
• Detect duplicate step names across river.ResumableStep and return a validation error. PR #1281
• Earlier backpressure from BatchCompleter when it's throughput is saturated with fewer warnings to console. PR #1292
• Series of minor optimizations in BatchCompleter raising throughput ~20% when it's the bottleneck in job processing (e.g. in benchmarks). PR #1293

Fixed

• Fix JobCancel having no effect on running jobs when using a poll-only driver (e.g. riverdatabasesql). The controlActionCancel event was silently dropped in fetchAndRunLoop's queueControlCh handler instead of being forwarded to maybeCancelJob. Note: this fix only works within a single process; cross-process cancels in poll-only setups must wait for the next poll cycle. PR #1245.
• Ensure jobs that return a custom timeout of -1 (no timeout) are never rescued. PR #1288.
• Detect numbered PostgreSQL REINDEX INDEX CONCURRENTLY artifacts like _ccnew1 and _ccold2 so the reindexer does not keep accumulating failed artifact indexes. Fixes #1296. PR #1297.

v0.39.0

⚠️ Breaking API change: rivermigrate.Migrator.Validate and rivermigrate.Migrator.ValidateTx now take a *rivermigrate.ValidateOpts parameter. Pass nil to preserve previous behavior. We normally endeavor not to make any breaking API changes, but this one will keep the API in a much nicer state, and is on an ancillary function that most installations won't be using. PR #1259

Added

• Added MetadataSet to stage job metadata updates from worker middleware, HookWorkBegin, workers, or HookWorkEnd, with changes persisted when the job is completed. PR #1269

Changed

• Add rivermigrate.ValidateOpts.TargetVersion so validation can check migrations up to a specific target version, matching the target-version behavior available on Migrate and MigrateTx. Notably, this is a breaking API change as the validate functions previously didn't take any options. PR #1259
• When using (*Migrator[TTx]).Migrate with a TargetVersion that's already applied, River now no-ops idempotently instead of returning an error as a user convenience. PR #1260
• Add logging statement for dropped job and queue subscription events at warn level when a subscriber buffer is full. PR #1271

Fixed

• Add a 10-second timeout around StandardPilot.JobGetAvailable so a stalled standard-pilot fetch no longer hangs a producer indefinitely. PR #1255
• Fixed rivertest.Worker.Work and WorkJob to honor a configured custom Config.Schema when transitioning a job to its running state. Previously, the running-state update ran unqualified and could fail on a connection whose search_path didn't include the configured schema. PR #1262

v0.38.0

Added

• Added new configuration Config.SoftStopTimeout to provide a cleaner way to gracefully stop a client. PR #1239