⚠️ 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.

⚠️ 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

Added

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

Fixed

• Wrap PeriodicJobEnqueuer.insertBatch database calls in a 30-second timeout. Previously, a stalled pgx Begin/Insert/Commit could hang the periodic enqueuer indefinitely, halting all periodic job insertion until the process was restarted or leader re-elected. PR #1251

Added

• Added "resumable jobs" that can be broken down into multiple steps and with a step persisted after it finishes that lets them skip work that's already been done. This is particularly useful for long running jobs that may experience a cancellation (like in the event of a deploy) during the span of their run. PR #1226.

Added

• Add QeueueBundle.Remove to remove an already added queue/producer. PR #1235 and PR #1240.

Fixed

• Fix unsafe concurrent producer map access in client. PR #1236.
• Mark schema replacements as Stable in sqlc templates, preventing query SQL from having to be reallocated over and over again.. PR #1242.
• Fix bug in sqltemplate cached path in order in which named args are passed to a query (previously, the order was unstable). PR #1243.

Fixed

• Fix accidentally inverted conditional on notifier error log check. PR #1231.

Changed

• Ignore errors like tls: failed to send closeNotify alert (but connection was closed anyway) when closing listeners. PR #1216.

Fixed

• Fixed leader election to track explicit database-issued leadership terms, reducing handoff flakiness and same-client reacquisition edge cases while making reelection and resign target the current leadership lease instead of a stale one. PR #1213.

Added

• Added Config.ReindexerIndexNames and ReindexerIndexNamesDefault() so the reindexer's target indexes can be customized from the public API. PR #1194.

Fixed

• Upon a client gaining leadership, its queue maintainer is given more than one opportunity to start. PR #1184.

Changed

• Jobs erroring or panicking no longer logs at the error/warn level because this is not indicative of a problem inside of River itself. These log statements have been demoted to info. PR #1190.

Fixed

• Fix in Client.Start where previously it was possible for a River client that only partially started before erroring to not try to start on subsequent Start invocations. PR #1187.