vibhorkum/pg_background v2.0

pg_background v2.0 — major release

on GitHub

pg_background 2.0 is a major cleanup release. The cookie-protected,
explicit-lifecycle API is now the only API, the _v2 suffix is retired
in favor of canonical unsuffixed names (with deprecated aliases kept for a
full major cycle), several composite types gained forward-compatibility
columns, and the supported PostgreSQL range is extended through 19 (beta).

Upgrading? The full, authoritative migration guide is
docs/MIGRATION.md.
Supported upgrade source is 1.8 or newer; pre-1.8 installs must first
reach 1.8 on the 1.10 line.

Highlights

The _v2 suffix is retired — unsuffixed names are canonical

With the v1 API gone, the _v2 suffix no longer distinguished anything.
2.0 makes the unsuffixed names canonical (pg_background_launch,
pg_background_result, pg_background_wait, pg_background_run, …).

No code change is required to upgrade. Every _v2 name that shipped
through 1.10 is kept as a thin deprecated alias that forwards to the
canonical function with identical behavior. Each alias carries a
DEPRECATED … Removed in 3.0 comment (visible via \df+). Migrate at your
own pace; new code should use the unsuffixed names.

The canonical names intentionally coexist with same-named objects of a
different kind, resolved by call syntax:

• pg_background_list — view (preferred for monitoring); pg_background_list() — raw set-returning function.
• pg_background_stats / pg_background_outcome — composite types; pg_background_stats() / pg_background_outcome(...) — functions.

PostgreSQL 19 beta support

• Validated against PostgreSQL 19 beta1 (build + installcheck + relocatable).
• Added the explicit header includes PG 19 no longer provides transitively
  (storage/proc.h, storage/latch.h, utils/wait_event.h,
  utils/timestamp.h); the version gate is now 14 ≤ PG_VERSION_NUM < 20.
• CI runs the regression and relocatable matrices on the postgres:19beta1
  image; the upgrade and assert jobs remain 14–18 during the beta cycle.

Breaking changes

Removed: the v1 API

The original v1 functions are gone: pg_background_launch(sql, queue_size)
returning int4, pg_background_result(pid), and pg_background_detach(pid).
The unsuffixed names are back with cookie-protected v2 semantics —
pg_background_launch now returns a pg_background_handle (pid + cookie),
not a bare int4. Capture both fields and pass the cookie to every later
operation on that worker.

Collapsed: cancel / wait overloads

The _grace and _timeout variants are merged into the base function with a
defaulted parameter:

• pg_background_cancel(pid, cookie, grace_ms DEFAULT 0)
• pg_background_wait(pid, cookie, timeout_ms DEFAULT 0) — always returns bool.
  timeout_ms <= 0 blocks indefinitely; timeout_ms > 0 waits up to N ms.
  timeout_ms = 0 does not poll — pass timeout_ms = 1 to poll.

Removed: pg_background_status_v2

Use to_jsonb(pg_background_outcome(pid, cookie)) instead.

Renamed: progress reporting (hard rename, no alias)

• pg_background_progress(pct, msg) → pg_background_report_progress(pct, msg)
• the pg_background_progress type → pg_background_progress_info

Renamed: privilege helpers (hard rename, no alias)

• grant_pg_background_privileges → pg_background_grant_privileges
• revoke_pg_background_privileges → pg_background_revoke_privileges

After the upgrade script runs, grants held by pgbackground_role are
reapplied automatically. Explicit grants you made to other roles for
renamed objects must be reissued.

Forward-compatible additions

These are non-breaking under named-field access; positional/SELECT *
decoding into an old-shaped row variable needs the new wider shape.

Security

• The SECURITY DEFINER privilege helpers are never granted to the executor
  role (privilege-escalation guard), enforced by a metadata-driven contract
  test.
• PUBLIC is locked down on every extension-registered object via a metadata
  sweep that runs last in both the fresh-install and upgrade scripts.

PostgreSQL compatibility

• Supported: PostgreSQL 14, 15, 16, 17, 18, and 19 (beta).
• CI matrix covers Ubuntu 22.04 and 24.04.

Installation

-- Fresh install
CREATE EXTENSION pg_background;

-- Upgrade from 1.10 (single hop)
ALTER EXTENSION pg_background UPDATE TO '2.0';

The 1.10 → 2.0 upgrade drops the entire 1.10 SQL surface and recreates the
full 2.0 surface so an upgraded install is byte-for-byte identical to a fresh
CREATE EXTENSION. Grants are reapplied automatically.

Full changelog / migration: docs/MIGRATION.md