Metadata-Version: 2.5
Name: pgbg
Version: 26.3.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

### Added

- `pgbg.NotifyDispatcher.wake()` that makes a dispatch loop you run yourself notice its stop event at once.
  [#3](https://github.com/hynek/pgbg/pull/3)


### Changed

- Stopping a dispatcher, subscribing, and closing a subscription take effect at once instead of within one *interval*.
  A `LISTEN` connection that PostgreSQL closes is replaced at once, too.
  *interval* now only sets how often an idle dispatcher checks that its connection is alive.
  [#3](https://github.com/hynek/pgbg/pull/3)

- As such, the default *interval* of `pgbg.NotifyDispatcher`, `pgbg.SupervisedDispatcher.start()`, and `pgbg.sqlalchemy.start_dispatcher()` went from 1 to 30 seconds.
  [#3](https://github.com/hynek/pgbg/pull/3)


---

[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).