There’s a special kind of joy in watching a database do some of the heavy lifting… without disturbing your app threads.
is promised pg_background:execute SQL asynchronously background worker processes Inside PostgreSQL, so that your client session can proceed – while the task runs in its own transaction.
This is a deceptively simple superpower:
- Start (or maintain) a long-running query without keeping the client connection open
- Run “autonomous transaction” style side effects (commit/rollback independently of the caller)
- Explicitly monitor, wait, isolate or cancel
- Keep the operational model “Postgres-native” instead of adding another functionality
What is pg_background (and what it is not)
pg_background enables PostgreSQL to execute SQL commands asynchronously in dedicated background worker processes. Unlike approaches such as opening other connections (for example, dblink) or performing client-side async orchestration, these workers run inside the server with local resources and their own transaction scope.
This is not a full-fledged scheduler. This is not a queuing platform. It’s a fast tool: “Run this SQL there, and let me decide how to interact with it.”
Why do you want this in production?
Here’s my opinion: Most teams don’t need more moving parts. They require less with better failure modes.
pg_background shines when you need it:
- Non-blocking operation:Launch long queries without pinning the client connection
- autonomous transactions: Commit/rollback independently of the caller’s transaction.
- Resource isolation and safe cleanup: Worker lifecycle is clear (launch/result/detach/cancel/wait)
- Server-side observability: List workers and view status/errors (v2)
General production pattern:
- background vacuum/analyze/reindex
- async backfill or data repair
- Fire and forget audit/outbox writes
- “Do the expensive part later” workflows (especially in OLTP-heavy apps)
Big deal: v2 API (recommended)
The project now strongly pushes new deployments towards the v2 API, which uses (pid, cookie) handles to protect against PID reuse issues (a real-world footgun in long-running systems).
From the repo docs, v2 brings: cookie-based detection, explicit cancellation vs detach, synchronous wait, and better monitoring via list tasks.
Instant Taste (v2)
That last point-separation is not canceled– This is called an important semantic difference.
Installation + an operating rule you should not ignore
Install is the standard extension build + create extension, but the “gotcha” is not subtle:
Background workers consume max_worker_processes.
So shape it intentionally.
The README walks you through enabling the extension and setting max_worker_processes.
What’s new in the latest release (v1.6 → v1.8)
In case you haven’t noticed recently: there has been a meaningful “production hardening” arc in the project.
v1.6 (released February 5, 2026): Production stabilization + v2 API becomes star
This release clearly positions itself as “stabilizes pg_background for production use” and introduces the recommended v2 API with cookie-based worker handles.
Main attractions include:
- v2 API with PID + cookie protection (protected against PID reuse)
- Better DSM Lifecycle Handling
- Safe error handling and memory cleanup
- Better observation/diagnosis
- PostgreSQL 12-18 compatibility
Fixed items called: void safety in error translation, race conditions in cleanup, memory reference leaks in error paths, clear error codes for cookie mismatches.
Known limitations that remain (still significant in actual deployments):
- Windows cancels limits
- COPY protocol intentionally disabled
- Transaction control is not allowed inside workers
v1.7 (merged on February 13, 2026): Security + Memory + CPU Efficiency
v1.7 is where the internals have had the sharp edges sanded away – especially around the handle protection and long running sessions.
Notable improvements listed in the v1.7 PR:
- Cookie generation switched to pg_strong_random() (cryptographically secure) instead of predictable structure
- A dedicated WorkerInfoMemoryContext to avoid long session memory bloat
- Exponential backoff polling in wait/cancel loops to reduce CPU churn
- Helpful refactor + better constants/documentation, as well as clearer null checking around DSM construction
v1.8 (released February 13, 2026): Operational controls + overview features + packaging updates
The v1.8 release advances the CI/packaging work and modernizes the supported version stance: refactoring Docker-based CI, tightening .gitignore, as well as removing PostgreSQL 13 and older to align with supported majors.
It also adds real operator-friendly features:
New in 1.8 (from Extension SQL and docs):
- pg_background_stats_v2() for session statistics
- pg_background_progress() + pg_background_get_progress_v2() for progress reporting
- New GUCs: pg_background.max_workers, pg_background.worker_timeout, pg_background.default_queue_size
- Internal improvements sought: stronger random cookies, dedicated memory references, exponential backoff polling, UTF-8 aware truncation, max-employee enforcement.
And if you’re upgrading, the compatibility table in the README is blunt: PG 14+ is the current minimum supported line, with guidance to use older pg_background versions for older Postgres heads.
A practical checklist for using pg_background safely
Here’s the “Don’t Make Tomorrow-You Hate Today-You” list:
- Unless you have legacy dependencies, use v2. PID reuse protection is worth it.
- Treat max_worker_processes as a capacity budget. Background work competes with everything else.
- Remember: Isolate ≠ Cancel. Detach means “stop tracking”, not “stop moving.”
- Designed for lump sum consumption. Read the result once; Archive them in case you need to replay them.
- Use the new knobs (v1.8+): Set limit of workers per-session, set timeouts, right size queue memory.
- Use progress + statistics for actual operations. Observability prevents “mysterious background gremlins”.
closing thoughts
The best infrastructure is one that works quietly and refuses to be dramatic.
pg_background is that kind of tool: it gives PostgreSQL a clean, clear async execution lane – now with safe handles (v2), robust internals (v1.7), and operator-friendly controls and telemetry (v1.8).
If you want, paste your target use case (VACUUM jobs, backfill, “autonomous transaction” pattern, async ETL, etc.) and I’ll suggest a production-ready pattern with Rails using the v2 API.
<a href