xtr-orm-messenger
A database transport for xtr-messenger: messages kept in a table on an xtr-orm connection, claimed by workers, delayed, redelivered and woken by notifications.
Why?
A queue needs a broker, and a broker is one more server to run, back up and watch. An application that already has a database can keep its messages there: in a table, on the connection xtr-orm already configures, sent in the same transaction as the changes they announce if it wants.
- 🗄️ No broker —
orm://defaultis the application's owndefaultconnection. - 🔒 Workers never collide — each claims the oldest due message
FOR UPDATE SKIP LOCKED. - ⏰ Delays — a
DelayStampmakes a message due later. - ♻️ Nothing is lost to a dead worker — a message never settled is handed out again.
- 🔔 No polling on PostgreSQL — a waiting worker is woken the moment a message is sent.
- 🤝 Sent with the handler's changes —
transactional=truewrites the message in the unit of work's session, so it commits or rolls back with them.
Install
uv add xtr-orm-messenger
uv add "xtr-messenger[orm]" # the same, from the message bus's side
It needs xtr-messenger and xtr-orm, which come with it. It
brings no database driver: a transport writes through the connection its DSN names, with the
driver the application installed for that connection — xtr-orm's postgres, mysql or
sqlite extra. On PostgreSQL through asyncpg, a waiting worker is woken by notifications; with
any other driver it polls. It ships no bundle: with a
container, the orm bundle registers the transport once this
package is installed.
Quick start
Without a container, hand the factory the connections it builds on and the envelope serializer the bus and its workers share:
from xtr_messenger import (
JsonSerializer,
MessageBusConfig,
MessageBusFactory,
TransportConfig,
WorkerFactory,
)
from xtr_orm import ConnectionRegistry
from xtr_orm_messenger import OrmTransportFactory
from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer
registry = ConnectionRegistry()
registry.register("default", engine=engine, migrator=migrator, database=database)
config = MessageBusConfig(
transports={"jobs": TransportConfig("orm://default", queue="jobs")},
routing={IngestDocument: "jobs"},
)
wire = JsonSerializer(Serializer([PydanticNormalizer()], [JsonEncoder()]))
factory = OrmTransportFactory(registry, wire)
await MessageBusFactory(config, [factory]).bus().dispatch(IngestDocument(document_id=1))
await WorkerFactory(config, [factory]).worker(["jobs"]).run()
The bus writes the message into messenger_messages; the worker claims it, hands it to its
handlers and deletes it. With a container all of that is wired for you.
How it works
| Step | What happens |
|---|---|
| Send | One row: the encoded envelope, its queue, created_at, and available_at — later by the delay, rounded up to a whole second |
| Claim | In one transaction, the oldest row of the queue that is due and not handed out is selected FOR UPDATE SKIP LOCKED and stamped delivered_at |
| Handle | The worker dispatches it; the envelope carries OrmReceivedStamp and TransportMessageIdStamp, both the row's id |
| Settle | Acknowledged or rejected, the row is deleted |
| Redeliver | A row handed out more than redeliver_timeout seconds ago is claimable again: its worker is taken for dead |
A worker that finds nothing due waits poll_interval seconds before asking again. On
PostgreSQL through asyncpg it listens instead: every send announces itself on the table's
channel, naming its queue, and the worker asks again at once — or after
check_delayed_interval, for a delayed message falling due. Listening holds one connection of
the pool for as long as the worker runs.
SQLite has no row locks, so the lock clause is left out there. A second worker reaching for the row another is claiming gets "database is locked", which counts as a conflict and is tried again.
Conflicts between workers — a deadlock, a lock wait that timed out — say nothing about the message. A poll sits through 3 in a row before it raises; an acknowledgement or a rejection tries again with a pause doubling from 100 ms. One whose database went away waits up to 5 seconds for it and is replayed once: losing an acknowledgement to a restart would hand the message out again.
A message that does not decode can never be handled, so it is rejected at once, its reason
logged on the messenger logger — never its body.
The DSN
# .env
MESSENGER_DSN=orm://default
The format is orm://<connection_name>: the name of a connection the application configures
in xtr-orm, for when it has several and the messages go on one other than default; orm://
alone is the default connection. The URL, the driver and the pool are the connection's. The
transport creates a table named messenger_messages the first time it runs. To name the table
otherwise, give table_name in the DSN:
# .env
MESSENGER_DSN=orm://default?table_name=your_custom_table_name
The queue a transport reads and writes is queue — ?queue=jobs, or
TransportConfig(dsn, queue="jobs") — the setting every xtr-messenger transport takes for it.
Options
Every option may go in the DSN's query string or in TransportConfig.options; options wins.
An unknown one is refused with UnknownTransportOptionError, a bad value with
InvalidTransportOptionError.
| Option | Default | What it sets |
|---|---|---|
queue |
default |
the queue this transport reads and writes; also TransportConfig(queue=...) |
table_name |
messenger_messages |
the table, a plain identifier |
redeliver_timeout |
3600 |
seconds after which a message handed out and never settled is handed out again |
auto_setup |
true |
create the table the first time an operation finds it missing |
poll_interval |
1.0 |
seconds a worker waits before asking again when nothing was due |
transactional |
false |
write the message in the session of the unit of work under way |
use_notify |
true |
on PostgreSQL through asyncpg, wait for notifications instead of polling |
check_delayed_interval |
60000 |
milliseconds a listening worker waits at most before asking anyway |
get_notify_timeout |
60000 |
milliseconds one wait for a notification lasts at most |
orm:// with no name uses the default connection. A name the application did not configure is
refused with InvalidOrmDsnError when the transport is built.
Sending with the handler's changes
With transactional=true, a message dispatched while a message is handled — or a request, or a
command: any unit of work — is written in that unit's session and sent only when the unit
commits. Run the orm_transaction middleware, or commit yourself: a session never commits on
its own. Outside a unit of work the message is written in a transaction of its own, as it is
without the option.
Looking into a queue
OrmTransport is a TransportInterface with more to ask:
transport = factory.transport("jobs", config.transports["jobs"])
await transport.count() # what a worker could claim now
async for envelope in transport.all(limit=10):
... # the same, oldest first
await transport.find(message_id) # one message, handed out or not
await transport.keepalive(envelope, seconds=600) # a long handler keeps its message
await transport.setup() # create the table ahead of time
keepalive restarts a message's redelivery clock; seconds is how long until the next call,
refused when longer than redeliver_timeout.
Use in an application
Everything adding this package to an application takes — and, read backwards, what removing it undoes. It ships no bundle: the orm bundle registers the transport, built on its connections, when the messenger bundle is active too.
- Install —
uv add xtr-orm-messenger, oruv add "xtr-messenger[orm]", beside xtr-messenger and xtr-orm set up as their Use in an application says. The database driver is the connection's own. - Recipe —
uv run xtr-recipes recipes:syncwrites nothing: there is no bundle to list, no configuration file, environment variable or ignore line. It prints the step naming a transport, which a recipe cannot make for you. - Configure — name a transport
orm://defaultin<app>/config/packages/messenger.pyand route messages to it, as below. - Run —
<script> orm:migrations:diffwrites the messages table of everyorm://transport into its connection's next revision; until it is applied, the transport creates the table the first time it runs, unlessauto_setup=false. A worker is<script> messenger:consume <transport>. - Remove — drop the
orm://transports and the routing to them, and a migration dropping the table. Thenuv remove xtr-orm-messenger. - Check —
debug:config messengerlists theorm://transports.
Everything else — the bundles, the connections, the bus — is xtr-orm's and xtr-messenger's.
# app/config/packages/messenger.py
from xtr_dependency_injection import configure
from xtr_messenger.bundle import MessageBusConfig, TransportConfig
@configure
def messenger() -> MessageBusConfig:
return MessageBusConfig(
transports={"jobs": TransportConfig("orm://default?auto_setup=false", queue="jobs")},
routing={IngestDocument: "jobs"},
)
The orm bundle registers OrmTransportFactory with the messenger, built on its
ConnectionRegistry and the messenger's envelope serializer, and consulted ahead of the
factories found by DSN scheme. A bus and every worker of the container share it, and so share
each transport. When the kernel shuts down, the connections workers listened on are given back.
Without a container, messages_tables(bus_config, connection, default_connection) names the
tables the transports of a bus configuration keep on a connection, and MessagesTableDriver
adds one to the MetaData a connection's migrations compare with.
Errors
Everything this library raises derives from OrmMessengerError, itself a
MessageBusError of xtr-messenger:
| Error | Raised when |
|---|---|
TransportError |
the database refuses what a transport asked — sending, claiming, settling, listing — or an envelope settled here was not received here; the driver's error is its cause |
InvalidOrmDsnError |
an orm:// DSN names a connection the application does not configure; also a LookupError |
Development
Developed in the python-xtr monorepo, under
packages/xtr-orm-messenger; run the commands below from there. The python-xtr-orm-messenger
repository is a read-only copy, so send issues and pull requests to the monorepo.
uv sync
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
Every test runs on SQLite files. The PostgreSQL suite under tests/postgresql/ runs when
XTR_TEST_POSTGRES_URL names a database, as an asyncpg URL:
XTR_TEST_POSTGRES_URL=postgresql+asyncpg://user:password@127.0.0.1/test uv run pytest tests/postgresql
License
MIT — see LICENSE.
Metadata
Release files for xtr-orm-messenger 6.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_orm_messenger-6.3.0.tar.gz | 29.6 kB | With provenance | Details for xtr_orm_messenger-6.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_orm_messenger-6.3.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_orm_messenger-6.3.0-py3-none-any.whl |
Total release size: 67.8 kB
Release files / xtr_orm_messenger-6.3.0.tar.gz
| Download URL | xtr_orm_messenger-6.3.0.tar.gz |
|---|---|
| Size | 29.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
475c3ee396e2839a22fd5e467c3201cf098c57ad3de58b53a13edfe110432614
|
|
BLAKE2b-256 checksum How to use checksums |
b257a7977c5ad12115f435b789fdbd5a96ad406901953d6e090b68a6512f4f95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / xtr_orm_messenger-6.3.0-py3-none-any.whl
| Download URL | xtr_orm_messenger-6.3.0-py3-none-any.whl |
|---|---|
| Size | 38.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c75b450362a2b709ba4d3909723377d533d4dd45ce16d6c768384d57872054ba
|
|
BLAKE2b-256 checksum How to use checksums |
ba5749d106de9027a5b7a1ce62f44a42932b1ab6fa222f93e86af8bfaa2125cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for xtr-orm-messenger 6.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xtr_orm_messenger-6.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.