simplebroker-pg

Postgres backend plugin for SimpleBroker.

This package is intentionally separate from simplebroker itself. SimpleBroker remains SQLite-first. This package adds a Postgres backend through the public backend plugin hook.

Requirements

  • Python 3.11+
  • PostgreSQL
  • A dedicated schema for SimpleBroker tables

public is intentionally rejected.

Installation

# Fresh install through SimpleBroker's convenience extra
pipx install "simplebroker[pg]"

# Add to an existing pipx-installed simplebroker (recommended)
pipx inject simplebroker simplebroker-pg

# Or install through the convenience extra in a project
uv add "simplebroker[pg]"

# Or install the extension directly with uv
uv add simplebroker-pg

# Or install the extension directly with pip
pip install simplebroker-pg

simplebroker[pg] still installs this package as a separate distribution. Postgres support is not built into the default simplebroker install.

Python Usage

from simplebroker import Queue
from simplebroker_pg import PostgresRunner

runner = PostgresRunner(
    "postgresql://postgres@127.0.0.1:54329/simplebroker_test",
    schema="simplebroker_app",
)

queue = Queue("jobs", runner=runner, persistent=True)
try:
    queue.write("hello")
    print(queue.read())
finally:
    queue.close()
    runner.close()

Multi-Queue Activity Waiters

Postgres supports simplebroker.create_activity_waiter_for_queues(...) with one process-local shared LISTEN/NOTIFY listener per DSN and schema. The waiter wakes when any watched queue receives activity, ignores unrelated queue notifications, and returns the same ActivityWaiter | None shape as the core API.

Wakeups are hints. After wait(timeout) returns True, callers should still drain queues through normal SimpleBroker reads or moves. Close the multi-queue waiter explicitly when the watcher lifecycle ends.

CLI Usage

Create .broker.toml in the project root, or use the configured BROKER_PROJECT_CONFIG_PATH / BROKER_PROJECT_CONFIG_NAME location:

version = 1
backend = "postgres"
target = "postgresql://postgres@127.0.0.1:54329/simplebroker_test"

[backend_options]
schema = "simplebroker_app"

Then use the normal CLI from any child directory with project scope enabled:

broker init
broker write jobs hello
broker read jobs

You can also run entirely from environment variables without a project config:

BROKER_BACKEND=postgres \
BROKER_BACKEND_TARGET='postgresql://postgres@127.0.0.1:54329/simplebroker_test' \
BROKER_BACKEND_SCHEMA='simplebroker_app' \
BROKER_BACKEND_PASSWORD='postgres' \
broker init

Notes:

  • In env-only backend configuration, BROKER_BACKEND_TARGET overrides the host/port/user/database parts.
  • BROKER_BACKEND_HOST, BROKER_BACKEND_PORT, BROKER_BACKEND_USER, BROKER_BACKEND_PASSWORD, and BROKER_BACKEND_DATABASE are only used when there is no target from project config or env.
  • When project TOML provides the target or schema, the project file wins. BROKER_BACKEND_PASSWORD can still be supplied from env and is never written to project TOML.
  • The Postgres database must already exist. broker init creates the managed schema/tables inside that database; it does not create the database itself.
  • Missing backend/plugin errors are distinct from target/auth errors. Invalid schema names, bad passwords, malformed targets, and missing databases are reported as validation or connection failures, not as "backend not available" errors.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.9.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for VanL from gravatar.com VanL

Credits

Author: Van Lindberg

License

MIT

Requires

Python >=3.11

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

simplebroker_pg-3.1.1.tar.gz (20.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

simplebroker_pg-3.1.1-py3-none-any.whl (26.9 kB view details)

Uploaded Python 3

File details

Details for the file simplebroker_pg-3.1.1.tar.gz.

File metadata

  • Download URL: simplebroker_pg-3.1.1.tar.gz
  • Upload date:
  • Size: 20.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for simplebroker_pg-3.1.1.tar.gz
Algorithm Hash digest
SHA256 96c4d78f4e6487f28c7a60b9411d931208e720d6af35c884797fe3f7af07a267
MD5 332fbb5f1dd85f99eb92b4cb7327424f
BLAKE2b-256 3bfc2716b237ed572bbcd75594a1fdfdc9bd77997a7ab3d18d9c1b39493cf6e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for simplebroker_pg-3.1.1.tar.gz:

Publisher: release-gate-pg.yml on VanL/simplebroker

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file simplebroker_pg-3.1.1-py3-none-any.whl.

File metadata

  • Download URL: simplebroker_pg-3.1.1-py3-none-any.whl
  • Upload date:
  • Size: 26.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for simplebroker_pg-3.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f6027835df3d79f5bd33850de27165a6cd6140410fb57ebd89bf645722b9a9d9
MD5 b0ad4c8c0f06e2b40230aecef9bbeacf
BLAKE2b-256 56e65019b5b2f29b0d43deb5cf60f382c4dad5c59403d7ce85ea302c73b2eb54

See more details on using hashes here.

Provenance

The following attestation bundles were made for simplebroker_pg-3.1.1-py3-none-any.whl:

Publisher: release-gate-pg.yml on VanL/simplebroker

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.9.1

2 files

3.9.0

2 files

3.8.0

2 files

3.6.0

2 files

3.5.2

2 files

3.5.1

2 files

3.5.0

2 files

3.3.2

2 files

3.3.1

2 files

3.3.0

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

This release

3.1.1 This release

2 files

3.1.0

2 files

3.0.0

2 files

2.5.0

2 files

2.4.0

2 files

2.3.0

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.1

2 files

2.0.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.1

2 files

1.5.0

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.9

2 files

1.0.7

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.1

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page