Metadata-Version: 2.4
Name: simplebroker-pg
Version: 1.1.1
Summary: Postgres backend plugin for SimpleBroker
Author-email: Van Lindberg <van.lindberg@gmail.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: psycopg-pool<4,>=3.1
Requires-Dist: psycopg[binary]<4,>=3
Requires-Dist: simplebroker<4,>=3.3.4
Provides-Extra: dev
Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.10+
- PostgreSQL
- A dedicated schema for SimpleBroker tables

`public` is intentionally rejected.

## Installation

```bash
# 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

```python
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:

```toml
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:

```bash
broker init
broker write jobs hello
broker read jobs
```

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

```bash
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.
