Metadata-Version: 2.5
Name: pgbg
Version: 26.2.0
Summary: PostgreSQL-orchestrated background threads for Python
Project-URL: Changelog, https://github.com/hynek/pgbg/blob/main/CHANGELOG.md
Project-URL: Documentation, https://pgbg.hynek.me/
Project-URL: Funding, https://github.com/sponsors/hynek
Project-URL: GitHub, https://github.com/hynek/pgbg
Project-URL: Mastodon, https://mastodon.social/@hynek
Project-URL: Bluesky, https://bsky.app/profile/hynek.me
Author-email: Hynek Schlawack <hs@ox.cx>
License-Expression: MIT
License-File: LICENSE
Keywords: background tasks,leader election,postgres,postgresql,psycopg
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: attrs
Requires-Dist: bgt
Requires-Dist: prometheus-client
Requires-Dist: psycopg>=3.2.10
Requires-Dist: structlog>=25.3.0
Provides-Extra: pool
Requires-Dist: psycopg-pool; extra == 'pool'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy>=2; extra == 'sqlalchemy'
Description-Content-Type: text/markdown

# *pgbg*

*PostgreSQL-orchestrated background threads for Python*


*pgbg* builds on [*bgt*](https://bgt.hynek.me/) (a great way to reliably run background threads) and adds PostgreSQL integration:

- A [**`NOTIFY` dispatcher**](https://brandur.org/notifier) that takes **one** database connection per process and wakes up an arbitrary number of background threads.

- A table-based **leader election with automatic failover**.
  Make sure only one process runs work at a time.

Even with database backing, background tasks are **not** a job queue like Celery or RQ[^but].
Common use cases include:

- Periodic cleanup duties for [expired caches](https://psycache.hynek.me/en/latest/cleanup/#pgbg) or sessions.
- Maintenance of eventually consistent read models.
- Lightweight background tasks with the [transactional outbox pattern](https://en.wikipedia.org/wiki/Inbox_and_outbox_pattern#The_outbox_pattern).

[^but]: But it's useful for *implementing* worker queues _\~ominous foreshadowing\~_.

---

The core needs and supports only [Psycopg 3](https://www.psycopg.org/psycopg3/docs/) for database access.
*pgbg* comes with optional support for [SQLAlchemy](https://www.sqlalchemy.org) in the `pgbg.sqlalchemy` module that connects everything to a SQLAlchemy `Engine`.
If you use [*psycopg-pool*](https://www.psycopg.org/psycopg3/docs/api/pool.html), you don't need an adapter at all:
pass your pool's `connection` method wherever *pgbg* asks for a connection provider.

<!-- --8<-- [end:spiel] -->

Check out our [step-by-step tutorial](https://pgbg.hynek.me/stable/tutorial/) to get an instant feel for the features!


## Installation

The package is available on [PyPI under the `pgbg` name](https://pypi.org/project/pgbg/).
It comes with two optional extras:

- `sqlalchemy` (`uv pip install 'pgbg[sqlalchemy]'`) currently only adds a `SQLAlchemy>=2` dependency.
- `pool` (`uv pip install 'pgbg[pool]'`) installs [*psycopg-pool*](https://www.psycopg.org/psycopg3/docs/api/pool.html).


## Documentation

Full documentation lives at **<https://pgbg.hynek.me/>**.


## Release Information

### Removed

- The supervision layer moved to the new [*bgt*](https://github.com/hynek/bgt) package, which *pgbg* now depends on.
  `pgbg.Supervisor`, `pgbg.Service`, `pgbg.SupervisedService`, `pgbg.IntervalOnlyWakeup`, `pgbg.as_work_factory`, `pgbg.exceptions.SuppressedCrashError`, and the `pgbg.typing.Loop`, `pgbg.typing.Wakeup`, `pgbg.typing.DoWork`, and `pgbg.typing.WorkFactory` protocols are gone.
  Import them from `bgt` instead; their behavior is unchanged.


### Added

- `pgbg.sqlalchemy.init_db()` that takes a SQLAlchemy Engine or Connection.
  [#1](https://github.com/hynek/pgbg/pull/1)


### Changed

- The `service.notified` log event is now called `service.woken`.
  It fires on any wakeup, not only on notifications.

- The restart counter is now called `bgt_supervisor_restarts_total`, because *bgt*'s supervisor drives every loop.
  The metrics of elected services keep their `pgbg_` prefix.
  Supervision log events now go to the `bgt` logger; everything else stays on `pgbg`.


---

[Full Changelog →](https://github.com/hynek/pgbg/blob/main/CHANGELOG.md)


## Credits

*pgbg* is written by [Hynek Schlawack](https://hynek.me/) and distributed under the terms of the [MIT license](https://choosealicense.com/licenses/mit/).

The development is kindly supported by my employer [Variomedia AG](https://www.variomedia.de/) and all my fabulous [GitHub Sponsors](https://github.com/sponsors/hynek).