{"@context":"https://w3id.org/codemeta/3.0","@type":"SoftwareSourceCode","identifier":"pkg:golang/github.com/riverqueue/river","name":"github.com/riverqueue/river","description":"Package river is a robust high-performance job processing system for Go and\nPostgres.\n\nSee homepage, docs, and godoc, as well as the River UI.\n\nBeing built for Postgres, River encourages the use of the same database for\napplication data and job queue. By enqueueing jobs transactionally along with\nother database changes, whole classes of distributed systems problems are\navoided. Jobs are guaranteed to be enqueued if their transaction commits, are\nremoved if their transaction rolls back, and aren't visible for work _until_\ncommit. See transactional enqueueing for more background on this philosophy.\n\nJobs are defined in struct pairs, with an implementation of `JobArgs` and one\nof `Worker`.\n\nJob args contain `json` annotations and define how jobs are serialized to and\nfrom the database, along with a \"kind\", a stable string that uniquely identifies\nthe job.\n\nWorkers expose a `Work` function that dictates how jobs run.\n\nJobs are uniquely identified by their \"kind\" string. Workers are registered on\nstart up so that River knows how to assign jobs to workers:\n\nA River `Client` provides an interface for job insertion and manages job\nprocessing and maintenance services. A client's created with a database pool,\ndriver, and config struct containing a `Workers` bundle and other settings.\nHere's a client `Client` working one queue (`\"default\"`) with up to 100 worker\ngoroutines at a time:\n\n## Insert-only clients\n\nIt's often desirable to have a client that'll be used for inserting jobs, but\nnot working them. This is possible by omitting the `Queues` configuration, and\nskipping the call to `Start`:\n\n`Workers` can also be omitted, but it's better to include it so River can check\nthat inserted job kinds have a worker that can run them.\n\n## Stopping\n\nThe client should also be stopped on program shutdown:\n\nThere are some complexities around ensuring clients stop cleanly, but also in a\ntimely manner. See graceful shutdown for more details on River's stop modes.\n\n`Client.InsertTx` is used in conjunction with an instance of job args to\ninsert a job to work on a transaction:\n\nSee the `InsertAndWork` example for complete code.\n\nBatch job insertion for efficiently inserting many jobs at once using\nPostgres `COPY FROM`.\n\nCancelling jobs from inside a work function.\n\nError and panic handling.\n\nMultiple queues to better guarantee job throughput, worker availability,\nand isolation between components.\n\nPeriodic and cron jobs.\n\nScheduled jobs that run automatically at their scheduled time in the\nfuture.\n\nSnoozing jobs from inside a work function.\n\nSubscriptions to queue activity and statistics, providing easy hooks for\ntelemetry like logging and metrics.\n\nTest helpers to verify that jobs are inserted as expected.\n\nTransactional job completion to guarantee job completion commits with\nother changes in a transaction.\n\nUnique jobs by args, period, queue, and state.\n\nWeb UI for inspecting and interacting with jobs and queues.\n\nWork functions for simplified worker implementation.\n\n## Cross language enqueueing\n\nRiver supports inserting jobs in some non-Go languages which are then worked by Go implementations. This may be desirable in performance sensitive cases so that jobs can take advantage of Go's fast runtime.\n\nSee developing River.\n\nExample_batchInsert demonstrates how many jobs can be inserted for work as\npart of a single operation.\n\n\nExample_completeJobWithinTx demonstrates how to transactionally complete\na job alongside other database changes being made.\n\n\nExample_cronJob demonstrates how to create a cron job with a more complex\nschedule using a third party cron package to parse more elaborate crontab\nsyntax.\n\n\nExample_customInsertOpts demonstrates the use of a job with custom\njob-specific insertion options.\n\n\nExample_errorHandler demonstrates how to use the ErrorHandler interface for\ncustom application telemetry.\n\n\nExample_globalHooks demonstrates the use of hooks to modify River behavior\nwhich are global to a River client.\n\n\nExample_globalMiddleware demonstrates the use of middleware to modify River\nbehavior which are global to a River client.\n\n\nExample_gracefulShutdown demonstrates a realistic-looking stop loop for\nRiver. It listens for SIGINT/SIGTERM (like might be received by a Ctrl+C\nlocally or on a platform like Heroku to stop a process) and when received,\ntries a soft stop that waits for work to finish. If it doesn't finish in\ntime, a second SIGINT/SIGTERM will initiate a hard stop that cancels all jobs\nusing context cancellation. A third will give up on the stop procedure and\nexit uncleanly.\n\n\nExample_insertAndWork demonstrates how to register job workers, start a\nclient, and insert a job on it to be worked.\n\n\nExample_jobArgsHooks demonstrates the use of hooks to modify River behavior.\n\n\nExample_jobCancel demonstrates how to permanently cancel a job from within\nWork using JobCancel.\n\n\nExample_jobCancelFromClient demonstrates how to permanently cancel a job from\nany Client using JobCancel.\n\n\nExample_jobSnooze demonstrates how to snooze a job from within Work using\nJobSnooze. The job will be run again after 5 minutes and the snooze attempt\nwill decrement the job's attempt count, ensuring that one can snooze as many\ntimes as desired without being impacted by the max attempts.\n\n\nExample_periodicJob demonstrates the use of a periodic job.\n\n\nExample_queuePause demonstrates how to pause queues to prevent them from\nworking new jobs, and later resume them.\n\n\nExample_scheduledJob demonstrates how to schedule a job to be worked in the\nfuture.\n\n\nExample_subscription demonstrates the use of client subscriptions to receive\nevents containing information about worked jobs.\n\n\nExample_uniqueJob demonstrates the use of a job with custom\njob-specific insertion options.\n\n\nExample_workFunc demonstrates the use of river.WorkFunc, which can be used to\neasily add a worker with only a function instead of having to implement a\nfull worker struct.","version":"v0.38.0","softwareVersion":"v0.38.0","license":"https://spdx.org/licenses/MPL-2.0","codeRepository":"https://github.com/riverqueue/river","issueTracker":"https://github.com/riverqueue/river/issues","url":"https://github.com/riverqueue/river","programmingLanguage":{"@type":"ComputerLanguage","name":"Go"},"dateCreated":"2023-11-08","dateModified":"2026-05-22","datePublished":"2026-05-22","copyrightYear":2023,"downloadUrl":"https://proxy.golang.org/github.com/riverqueue/river/@v/v0.38.0.zip","softwareHelp":{"@type":"WebSite","url":"https://pkg.go.dev/github.com/riverqueue/river#section-documentation"},"applicationCategory":"go","runtimePlatform":"go","developmentStatus":"active","sameAs":["https://pkg.go.dev/github.com/riverqueue/river"],"https://www.w3.org/ns/activitystreams#likes":4485,"https://forgefed.org/ns#forks":124}