xtr-orm 2.0.0__tar.gz → 3.0.0__tar.gz

{xtr_orm-2.0.0 → xtr_orm-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-orm
-Version: 2.0.0
+Version: 3.0.0
 Summary: Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection.
 Keywords: orm,database,migrations,sqlalchemy,alembic,asyncio
 Author: Xterr
@@ -20,11 +20,11 @@ Requires-Dist: advanced-alchemy>=1.11
 Requires-Dist: alembic>=1.20
 Requires-Dist: sqlalchemy[asyncio]>=2.0.41
 Requires-Dist: typing-extensions>=4.4
-Requires-Dist: xtr-logging-contracts>=2.0,<3
-Requires-Dist: xtr-console>=2.0,<3 ; extra == 'console'
-Requires-Dist: xtr-dependency-injection>=2.0,<3 ; extra == 'di'
-Requires-Dist: xtr-service-contracts>=2.0,<3 ; extra == 'di'
-Requires-Dist: xtr-messenger>=2.0,<3 ; extra == 'messenger'
+Requires-Dist: xtr-logging-contracts>=3.0,<4
+Requires-Dist: xtr-console>=3.0,<4 ; extra == 'console'
+Requires-Dist: xtr-dependency-injection>=3.0,<4 ; extra == 'di'
+Requires-Dist: xtr-service-contracts>=3.0,<4 ; extra == 'di'
+Requires-Dist: xtr-messenger>=3.0,<4 ; extra == 'messenger'
 Requires-Dist: asyncmy>=0.2.9 ; extra == 'mysql'
 Requires-Dist: asyncpg>=0.29 ; extra == 'postgres'
 Requires-Dist: aiosqlite>=0.20 ; extra == 'sqlite'
@@ -202,15 +202,19 @@ removing it undoes.
 - **Install** — `uv add "xtr-orm[di,console,postgres]"`; `mysql` or `sqlite` instead of
   `postgres` for those databases; drop `console` to go without the commands; add `messenger`
   for the [message bus middleware](#message-bus-middleware).
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
+  *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/orm.py` with the
+  `default` connection, and `DATABASE_URL` in `.env`. It prints the middleware step, which a recipe
+  cannot make for you.
 - **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
   `xtr_orm.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
   With the messenger bundle active too, the [middleware](#message-bus-middleware) are
   registered for a bus to list.
-- **Configure** — optional: with no configuration there is one connection, `default`, reading
-  `DATABASE_URL`, with its revisions in `migrations` in the project directory and diffs
-  against the models advanced-alchemy registers. Connections, replicas and table definitions go
-  in `<app>/config/orm.py`, a `@configure` function returning `OrmConfig` — see
+- **Configure** — the recipe writes a starting `<app>/config/orm.py` with the `default`
+  connection reading `DATABASE_URL`, its revisions in `migrations` in the project directory and
+  diffs against the models advanced-alchemy registers. Add connections, replicas and table
+  definitions to that `@configure` function returning `OrmConfig` — see
   [Kernel / bundle](#kernel--bundle).
 - **Environment** — `DATABASE_URL`, read when a connection is first used — engine, session,
   migrator or command — not when the application boots. Its query may carry options; see

{xtr_orm-2.0.0 → xtr_orm-3.0.0}/README.md

@@ -163,15 +163,19 @@ removing it undoes.
 - **Install** — `uv add "xtr-orm[di,console,postgres]"`; `mysql` or `sqlite` instead of
   `postgres` for those databases; drop `console` to go without the commands; add `messenger`
   for the [message bus middleware](#message-bus-middleware).
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
+  *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/orm.py` with the
+  `default` connection, and `DATABASE_URL` in `.env`. It prints the middleware step, which a recipe
+  cannot make for you.
 - **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
   `xtr_orm.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
   With the messenger bundle active too, the [middleware](#message-bus-middleware) are
   registered for a bus to list.
-- **Configure** — optional: with no configuration there is one connection, `default`, reading
-  `DATABASE_URL`, with its revisions in `migrations` in the project directory and diffs
-  against the models advanced-alchemy registers. Connections, replicas and table definitions go
-  in `<app>/config/orm.py`, a `@configure` function returning `OrmConfig` — see
+- **Configure** — the recipe writes a starting `<app>/config/orm.py` with the `default`
+  connection reading `DATABASE_URL`, its revisions in `migrations` in the project directory and
+  diffs against the models advanced-alchemy registers. Add connections, replicas and table
+  definitions to that `@configure` function returning `OrmConfig` — see
   [Kernel / bundle](#kernel--bundle).
 - **Environment** — `DATABASE_URL`, read when a connection is first used — engine, session,
   migrator or command — not when the application boots. Its query may carry options; see

{xtr_orm-2.0.0 → xtr_orm-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "2.0.0"
+version = "3.0.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,7 +30,7 @@ dependencies = [
     "alembic>=1.20",
     "sqlalchemy[asyncio]>=2.0.41",
     "typing-extensions>=4.4",
-    "xtr-logging-contracts>=2.0,<3",
+    "xtr-logging-contracts>=3.0,<4",
 ]
 
 [[project.authors]]
@@ -42,15 +42,18 @@ postgres = ["asyncpg>=0.29"]
 sqlite = ["aiosqlite>=0.20"]
 mysql = ["asyncmy>=0.2.9"]
 di = [
-    "xtr-dependency-injection>=2.0,<3",
-    "xtr-service-contracts>=2.0,<3",
+    "xtr-dependency-injection>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
 ]
-console = ["xtr-console>=2.0,<3"]
-messenger = ["xtr-messenger>=2.0,<3"]
+console = ["xtr-console>=3.0,<4"]
+messenger = ["xtr-messenger>=3.0,<4"]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 orm = "xtr_orm.bundle:OrmBundle"
 
+[project.entry-points.xtr_recipes]
+orm = "xtr_orm.recipe"
+
 [dependency-groups]
 dev = [
     "basedpyright>=1.21",
@@ -60,11 +63,11 @@ dev = [
     "anyio>=4.0",
     "ty>=0.0.83",
     "aiosqlite>=0.20",
-    "xtr-console>=2.0,<3",
-    "xtr-dependency-injection>=2.0,<3",
-    "xtr-logging>=2.0,<3",
-    "xtr-messenger>=2.0,<3",
-    "xtr-service-contracts>=2.0,<3",
+    "xtr-console>=3.0,<4",
+    "xtr-dependency-injection>=3.0,<4",
+    "xtr-logging>=3.0,<4",
+    "xtr-messenger>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
 ]
 
 [build-system]

{xtr_orm-2.0.0 → xtr_orm-3.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "2.0.0"
+version = "3.0.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,7 +26,7 @@ dependencies = [
     "alembic>=1.20",
     "sqlalchemy[asyncio]>=2.0.41",
     "typing-extensions>=4.4",
-    "xtr-logging-contracts>=2.0,<3",
+    "xtr-logging-contracts>=3.0,<4",
 ]
 
 [project.optional-dependencies]
@@ -40,14 +40,14 @@ mysql = [
     "asyncmy>=0.2.9",
 ]
 di = [
-    "xtr-dependency-injection>=2.0,<3",
-    "xtr-service-contracts>=2.0,<3",
+    "xtr-dependency-injection>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
 ]
 console = [
-    "xtr-console>=2.0,<3",
+    "xtr-console>=3.0,<4",
 ]
 messenger = [
-    "xtr-messenger>=2.0,<3",
+    "xtr-messenger>=3.0,<4",
 ]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
@@ -55,6 +55,10 @@ messenger = [
 [project.entry-points."xtr_dependency_injection.bundles"]
 orm = "xtr_orm.bundle:OrmBundle"
 
+# Advertises the recipe — what *Use in an application* takes — for recipes:sync.
+[project.entry-points."xtr_recipes"]
+orm = "xtr_orm.recipe"
+
 [dependency-groups]
 dev = [
     "basedpyright>=1.21",
@@ -65,11 +69,11 @@ dev = [
     "ty>=0.0.83",
     # Every test runs on SQLite files under the test's own directory: no server.
     "aiosqlite>=0.20",
-    "xtr-console>=2.0,<3",
-    "xtr-dependency-injection>=2.0,<3",
-    "xtr-logging>=2.0,<3",
-    "xtr-messenger>=2.0,<3",
-    "xtr-service-contracts>=2.0,<3",
+    "xtr-console>=3.0,<4",
+    "xtr-dependency-injection>=3.0,<4",
+    "xtr-logging>=3.0,<4",
+    "xtr-messenger>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
 ]
 
 [build-system]

xtr_orm-3.0.0/src/xtr_orm/.agents/skills/xtr-orm/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: xtr-orm
+description: How to configure database connections, inject async sessions and run versioned schema migrations with xtr-orm. Use when application code needs an AsyncEngine, an AsyncSession, a session per request or per message, read replicas, a DATABASE_URL, a new migration revision, a schema diff against models, the orm:migrations:* or orm:database:* console commands, one transaction per message on a bus, or when adding OrmBundle to an application on xtr-dependency-injection.
+---
+
+# xtr-orm
+
+A connection is configuration. You name each database once — URL, replicas, engine and session
+options, where its revisions live — and the bundle hands out the engine, the session maker, the
+session of the current unit of work, a `Migrator` and a `DatabaseManager`, each qualified by the
+connection's name. Everything is async; there is no sync counterpart.
+
+## Quick reference
+
+- Inject `Injected[AsyncSession]` for the default connection;
+  `Annotated[AsyncSession, Target("reports")]` for another. Never build a session yourself.
+- Name databases in `<app>/config/orm.py` with a `@configure` function returning `OrmConfig`.
+- Set `DATABASE_URL` with an async driver: `postgresql+asyncpg://`, `mysql+asyncmy://`,
+  `sqlite+aiosqlite:///`. Engine and session options may ride on its query.
+- Write a revision from your models: `orm:migrations:diff --message "add invoices"`. Apply:
+  `orm:migrations:migrate`. Read it: `orm:migrations:status`.
+- Without a container: `Migrator(engine, MigrationsConfig(directory="migrations"), Base.metadata)`.
+- One transaction per message: list `orm_transaction` in the bus's `middleware`; handlers never
+  commit.
+- On SQLite, set `MigrationsConfig(render_as_batch=True)` or table alterations cannot be written.
+
+## Inject a session
+
+```python
+from typing import Annotated
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+from xtr_dependency_injection import Injected, Target, as_service
+
+
+@as_service
+class InvoiceRepository:
+    def __init__(self, session: Injected[AsyncSession]) -> None:
+        self._session = session
+
+
+async def report(
+    session: Annotated[AsyncSession, Target("reports")],
+    engine: Annotated[AsyncEngine, Target("reports")],
+) -> None: ...
+```
+
+Per connection, qualified by name — and unqualified for the default one:
+
+| Service | What it is |
+|---|---|
+| `AsyncSession` | The session of the current unit of work: a request, a message, a command. Closed, and rolled back when not committed, as the unit ends |
+| `AsyncEngine` | The engine on the primary database. Disposed when the container closes |
+| `async_sessionmaker[AsyncSession]` | The session maker; `RoutingAsyncSessionMaker` when the connection has replicas |
+| `SQLAlchemyAsyncConfig` | advanced-alchemy's configuration, for its repositories and services |
+| `Migrator` / `DatabaseManager` | The connection's revisions / its database, both on the primary |
+| `ConnectionRegistry` | Every connection by name, unqualified — what the commands use |
+
+A session is scoped to the unit of work: asking for one outside any raises
+`SessionUnavailableError`. Do not cache a session on a singleton.
+
+## Migrations
+
+`Migrator` is the whole surface. Every method opens its own connection; `generate` reads files
+only.
+
+| Call | Does |
+|---|---|
+| `await migrator.status()` | `current`, `latest`, `previous`, `next`, `available`, `executed`, `new`, `executed_unavailable`, `is_up_to_date` |
+| `await migrator.migrate(target)` | Runs every revision to `target`; returns `ExecutionResult`s. `plan(target)` plans it, `migrate_sql(target)` writes the SQL |
+| `await migrator.execute(versions, Direction.UP)` | Exactly those revisions, nothing before or after. `plan_for_versions(versions, direction)` and `execute_sql(...)` alongside |
+| `migrator.generate("message")` | Writes an empty revision after the latest (not awaited) |
+| `await migrator.diff("message")` | Writes what the table definitions add; takes `allow_empty=`, `from_empty_schema=` |
+| `await migrator.dump_schema("message", table_filters=...)` | A first revision creating every table an existing database has |
+| `await migrator.add_versions(v)` / `add_all_versions()` | Records revisions as applied, running nothing |
+| `await migrator.delete_versions(v)` / `delete_all_versions()` | Records them as not applied |
+| `await migrator.rollup()` | Forgets every applied revision, then records the single remaining one |
+
+A **target** is a revision id (full or partial), a relative one (`+1`, `-2`, `ae10+1`), or
+`latest`, `first`, `next`, `prev`, `current`. A revision already applied is migrated *down* to.
+
+Two tables, in one schema: `alembic_version` holds where the database **is** and decides what a
+migration runs; `alembic_version_history` holds a row per revision ever applied, with
+`executed_at` and `execution_time` in milliseconds.
+
+`execute` is refused before touching the database unless the version table stays truthful: going
+up a revision must not be applied and must follow only applied ones; going down it must be applied
+and followed by none that is. **Up to date** compares the database's versions with the revision
+files, not its schema with your models; `diff` does the latter.
+
+Without a container:
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from xtr_orm import MigrationsConfig, Migrator
+
+from app.models import Base
+
+engine = create_async_engine("sqlite+aiosqlite:///shop.db")
+migrator = Migrator(
+    engine,
+    MigrationsConfig(directory="migrations", render_as_batch=True),
+    Base.metadata,
+)
+
+revision = await migrator.diff("add invoices")  # AvailableMigration, or None with nothing to do
+await migrator.migrate()
+```
+
+`MigrationsConfig` fields you reach for most: `directory` (relative to the working directory —
+under a kernel start it with `%kernel.project_dir%`), `render_as_batch` (SQLite),
+`compare_type` / `compare_server_default` (off by default), `version_table` / `history_table`,
+`file_template`, `post_write_hooks` (a formatter), `transaction_per_migration`,
+`template_directory`, `user_module_prefix`. See [references/migrations.md](references/migrations.md)
+for every field and for writing your own `script.py.mako`.
+
+## Console commands
+
+Needs the `console` extra. Every command takes `--connection NAME`, defaulting to
+`OrmConfig.default_connection`. The ones that change the database ask first; `-n` answers yes.
+
+| Command | Does |
+|---|---|
+| `orm:migrations:diff [--message M]` | Writes what the models add; the database must be up to date first |
+| `orm:migrations:migrate [VERSION]` | Runs every revision to `VERSION`, `latest` by default |
+| `orm:migrations:status` / `:list` / `:current` / `:latest` | Where the database stands |
+| `orm:migrations:up-to-date` | Exits non-zero when revisions are not applied — for a deploy check |
+| `orm:database:create` / `:drop --force` | The database itself |
+| `orm:run-sql SQL` | Runs one statement, committed |
+
+Nine more, and every flag: [references/commands.md](references/commands.md).
+
+Deploy order: `orm:migrations:migrate` from **one** place, before the application starts —
+migrations take no lock.
+
+Without a container, hand the commands their connections once:
+
+```python
+from xtr_orm import ConnectionRegistry, DatabaseManager
+from xtr_orm.command import use_connections
+
+registry = ConnectionRegistry()
+registry.register("default", engine=engine, migrator=migrator, database=DatabaseManager(url))
+use_connections(registry)
+```
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists `OrmBundle`,
+writes a starting `config/orm.py` with the `default` connection, and `DATABASE_URL` in `.env`. That
+is the steps below a recipe can do; the middleware it prints for you to add.
+
+1. **Install** — `uv add "xtr-orm[di,console,postgres]"`; `mysql` or `sqlite` instead of
+   `postgres`; drop `console` to go without the commands; add `messenger` for the bus middleware.
+2. **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`
+   (`from xtr_orm.bundle import OrmBundle`).
+3. **Brings along** — the logging and console bundles when those packages are installed, each
+   optional. With the logging bundle active an `orm` channel is added and every migrator logs the
+   revisions it runs there.
+4. **Configure** — optional. With no configuration there is one connection, `default`, reading
+   `DATABASE_URL`, revisions in `migrations` in the project directory, diffing against the models
+   advanced-alchemy registers.
+
+   ```python
+   # <app>/config/orm.py
+   from xtr_dependency_injection import configure, env
+   from xtr_orm.bundle import ConnectionConfig, MigrationsConfig, OrmConfig
+
+   from app.models import Base
+
+
+   @configure
+   def orm() -> OrmConfig:
+       return OrmConfig(
+           connections={
+               "default": ConnectionConfig(
+                   url=env("DATABASE_URL"),
+                   replicas={"replica1": env("DATABASE_REPLICA_URL")},
+                   engine_options={"pool_size": 10, "pool_pre_ping": True},
+                   session_options={"expire_on_commit": False},
+                   metadata=Base.metadata,
+                   migrations=MigrationsConfig(directory="%kernel.project_dir%/migrations"),
+               ),
+               "reports": ConnectionConfig(url=env("REPORTS_URL"), bind_key="reports"),
+           },
+       )
+   ```
+
+5. **Environment** — `DATABASE_URL`, read when a connection is first used (engine, session,
+   migrator or command), not at boot. Its query may carry options — see
+   [references/connections.md](references/connections.md).
+6. **Use** — inject `AsyncSession`; run `orm:migrations:*` from the console.
+7. **Ignore** — nothing: commit `migrations/`.
+8. **Check** — `debug:bundles` shows `orm` as `listed` and `active`, and
+   `orm:migrations:status` reaches the database.
+9. **Remove** — take the `orm_*` entries out of every bus's `middleware`, drop the `BUNDLES`
+   entry, delete `<app>/config/orm.py`, then `uv remove xtr-orm`.
+
+`OrmConfig` has two fields: `default_connection` (`"default"`) and `connections`
+(`{"default": ConnectionConfig()}`). Two connections may not keep their revisions in one
+directory; a non-default connection defaults to `%kernel.project_dir%/migrations/<name>`. Every
+`ConnectionConfig` field, replicas and URL options: [references/connections.md](references/connections.md).
+
+## One transaction per message
+
+With the `messenger` extra and both bundles active, three middleware are registered by name.
+Nothing is added to a bus by itself — the bus lists what it wants, and order matters.
+
+```python
+# <app>/config/messenger.py
+MessageBusConfig(
+    middleware=[
+        "orm_close_connection",  # outermost: closes after the transaction ended
+        "orm_transaction",
+        {"orm_transaction": {"connection_name": "reports"}},
+        "orm_open_transaction_logger",  # inside orm_transaction
+    ],
+)
+```
+
+| Name | Class | Arguments |
+|---|---|---|
+| `orm_transaction` | `TransactionMiddleware` | `connection_name`, the default connection when left out |
+| `orm_close_connection` | `CloseConnectionMiddleware` | `connection_names`, every connection in use when left out |
+| `orm_open_transaction_logger` | `OpenTransactionLoggerMiddleware` | `connection_names`, as above |
+
+A handler asks for `Injected[AsyncSession]` like any service and adds rows; it never commits.
+
+- Every handler of a message shares one session per connection. A message dispatched while
+  another is handled joins its unit of work, in a savepoint of its own.
+- A follow-up dispatched to a transport goes out at once unless stamped:
+  `await bus.dispatch(SendReceipt(order.id), DispatchAfterCurrentBusStamp())` sends it only after
+  the commit, and never after a rollback.
+- Only a message a worker consumed closes connections afterwards; `sync://` closes nothing.
+- Find a dropped connection with the engine option `pool_pre_ping`, not a middleware.
+
+More, including building the middleware without a container:
+[references/messenger.md](references/messenger.md).
+
+## Creating and dropping a database
+
+```python
+from xtr_orm import DatabaseManager
+
+database = DatabaseManager("postgresql+asyncpg://app:secret@db/shop")
+await database.exists()
+await database.create(if_not_exists=True)  # True when it created one
+await database.drop(if_exists=True)
+database.backend, database.database, database.safe_url  # properties
+```
+
+The server is reached through its maintenance database — `postgres`, `master`, none on MySQL and
+MariaDB — carrying every connection parameter of the URL but the database name. A SQLite database
+is its file. Any other server raises `UnsupportedDatabaseError`.
+
+## Errors
+
+Every error derives from `OrmError`.
+
+| Error | Raised when |
+|---|---|
+| `InvalidArgumentError` | A configuration cannot be used: an empty name, an unknown engine/session option, a URL option that does not read. Also a `ValueError` |
+| `MigrationError` | A migration is refused or revisions cannot be read: an unknown or ambiguous version, a revision out of order, a diff of a database behind its revisions |
+| `UnknownConnectionError` | A connection asked for by a name nothing registered. Also a `LookupError` |
+| `UnsupportedDatabaseError` | A database created or dropped on a server whose statements are not known |
+| `SessionUnavailableError` | A session asked for outside a unit of work, or of a connection registered without one |
+
+## Do not
+
+- Do not use a sync driver. `postgresql://` fails; write `postgresql+asyncpg://`.
+- Do not commit in a handler under `orm_transaction`, and do not wrap one in
+  `async with session.begin()` — the transaction is already open and it is refused.
+- Do not build engines or sessions by hand in application code, and do not hold a session past its
+  unit of work or store one on a singleton.
+- Do not write an `env.py` or an `alembic.ini`; the package runs the revisions itself.
+- Do not expect `up-to-date` to notice a model change — run `diff` — and do not run `diff` against
+  a database behind its revisions; migrate first.
+- Do not leave `render_as_batch` off on SQLite.
+- Do not run `orm:migrations:migrate` from several processes at once; it takes no lock.
+- Do not rely on advanced-alchemy's process-wide model registry when two kernels share one
+  process: give each connection its `metadata`.
+- Do not expect a timezone on `executed_at` outside PostgreSQL; it is naive elsewhere.

xtr_orm-3.0.0/src/xtr_orm/.agents/skills/xtr-orm/references/commands.md

@@ -0,0 +1,67 @@
+# The `orm:*` console commands
+
+Needs the `console` extra: `uv add "xtr-orm[console]"`. With a container, the bundle declares them
+when the console bundle is active, and each acts on the connections the bundle registered.
+
+Every command takes `--connection NAME`; the default connection is used without it. The ones that
+change the database ask first, and `-n` answers yes. `--message` names the revision and its file.
+
+## The database
+
+| Command | Flags |
+|---|---|
+| `orm:database:create` | `--if-not-exists` — do nothing, successfully, when it exists |
+| `orm:database:drop` | `--force` / `-f` — required, the confirmation that everything may be lost; `--if-exists` |
+| `orm:run-sql SQL` | `--force-fetch` — show rows even when the statement does not look like it returns any. The statement is committed |
+
+## Reading where the database stands
+
+| Command | Shows |
+|---|---|
+| `orm:migrations:current` | The revisions the version table holds; `base` for none |
+| `orm:migrations:latest` | The revisions no other follows |
+| `orm:migrations:list` | Every revision with its status, when it ran and how long it took |
+| `orm:migrations:status` | The two tables, the database, previous / current / next / latest, and the counts |
+| `orm:migrations:up-to-date` | Exits 1 with revisions not applied. `--fail-on-unregistered` / `-u` exits 2 for applied revisions whose file is gone; `--list-migrations` / `-l` names them |
+
+`up-to-date` is the deploy check: it compares the database's versions with the revision files, not
+its schema with your models.
+
+## Running revisions
+
+| Command | Flags |
+|---|---|
+| `orm:migrations:migrate [VERSION]` | `VERSION` defaults to `latest`; also a full or partial id, a relative one (`+1`, `-2`), `first`, `next`, `prev`, `current`. `--dry-run` reports the plan; `--write-sql PATH` writes the SQL instead of running it; `--allow-no-migration` succeeds when there is nothing to run |
+| `orm:migrations:execute VERSION...` | `--up` (the default) or `--down`; `--dry-run`; `--write-sql PATH`. Runs exactly those revisions and nothing before or after. Going up each must not be applied and must follow only applied ones; going down each must be applied and be followed by none that is |
+
+`--write-sql` writes to the file named, or to a dated file in the directory named.
+
+## Writing revisions
+
+| Command | Flags |
+|---|---|
+| `orm:migrations:generate` | `--message M`. An empty revision after the latest, to fill in by hand |
+| `orm:migrations:diff` | `--message M`; `--allow-empty-diff` writes a revision even when nothing differs; `--from-empty-schema` writes every table as if the database were empty. The database must be at the latest revisions first |
+| `orm:migrations:dump-schema` | `--message M`; `--filter-tables RE`, repeatable, dumps only the tables whose name the expression finds. For a database that predates its revisions, so there must be none yet. Written, not applied — follow with `orm:migrations:rollup` |
+
+## Recording without running
+
+| Command | Flags |
+|---|---|
+| `orm:migrations:version [VERSION]` | Exactly one of `--add` / `--delete`; `--all` for every revision instead of one. Adding, the revision must follow only applied ones; deleting, no applied revision may follow it. An applied revision whose file is gone can always be deleted |
+| `orm:migrations:rollup` | Forgets every applied revision, then records the single remaining one as all there is |
+
+## Without a container
+
+```python
+from xtr_orm import ConnectionRegistry, DatabaseManager
+from xtr_orm.command import use_connections
+
+registry = ConnectionRegistry()
+registry.register("default", engine=engine, migrator=migrator, database=DatabaseManager(url))
+use_connections(registry)
+```
+
+The command classes are exported from `xtr_orm.command` — `MigrationsMigrateCommand`,
+`MigrationsDiffCommand`, `DatabaseCreateCommand` and the rest — for a console application to
+register itself.

xtr_orm-3.0.0/src/xtr_orm/.agents/skills/xtr-orm/references/connections.md

@@ -0,0 +1,97 @@
+# ConnectionConfig, URL options and read replicas
+
+`from xtr_orm.bundle import ConnectionConfig`. A frozen dataclass, buildable with no arguments.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `url` | `"%env(DATABASE_URL)%"` | The database URL, with an async driver. Its query may carry options — see below |
+| `engine_options` | `{}` | `echo`, `pool_size`, `max_overflow`, `pool_pre_ping`, `pool_recycle`, `isolation_level`, `connect_args`, `execution_options`, … |
+| `session_options` | `{}` | `expire_on_commit`, `autoflush`, `info`, … |
+| `alchemy_options` | `{}` | Any other option of advanced-alchemy's configuration, such as `enable_touch_updated_timestamp_listener` |
+| `replicas` | `{}` | Read replicas, each a URL by name |
+| `keep_replica` | `False` | Go back to the replicas once a session commits |
+| `bind_key` | `None` | Which table definitions belong to this database when models declare several |
+| `metadata` | `None` | The table definitions a diff compares the database with; those registered for `bind_key` when `None` |
+| `migrations` | `None` | A `MigrationsConfig`; `%kernel.project_dir%/migrations` for the default connection, `.../migrations/<name>` for any other, when `None` |
+
+An unknown key in `engine_options`, `session_options` or `alchemy_options` raises
+`InvalidArgumentError` at configuration time, naming the options that exist. Options the bundle
+sets itself — `connection_string`, `engine_config`, `session_config`, `bind_key`, `metadata`,
+`engine_instance`, `session_maker`, `alembic_config`, `create_engine_callable`,
+`session_maker_class`, `routing_config` — are refused in `alchemy_options`.
+
+An empty `url`, an empty replica name or an empty replica URL is refused too. The default
+`"%env(DATABASE_URL)%"` is a placeholder resolved when the connection is first used, so a missing
+variable fails that use, not the boot.
+
+## Options in the URL
+
+One environment variable can configure a whole connection. An engine option, a session option or
+`keep_replica` is taken out of the query and merged over what the configuration set — **the URL
+wins**. Every other query parameter stays on the URL for the driver.
+
+```sh
+DATABASE_URL="postgresql+asyncpg://app:secret@db/shop?pool_size=20&expire_on_commit=false&ssl=require"
+```
+
+| Read from the URL | Options |
+|---|---|
+| Engine | `echo`, `echo_pool`, `enable_from_linting`, `hide_parameters`, `insertmanyvalues_page_size`, `isolation_level`, `label_length`, `logging_name`, `max_identifier_length`, `max_overflow`, `paramstyle`, `pool_logging_name`, `pool_pre_ping`, `pool_recycle`, `pool_size`, `pool_timeout`, `pool_use_lifo`, `query_cache_size`, `use_insertmanyvalues` |
+| Session | `autobegin`, `autoflush`, `expire_on_commit`, `join_transaction_mode`, `twophase` |
+| Connection | `keep_replica` |
+
+Flags read `1`/`true`/`yes`/`on` and `0`/`false`/`no`/`off`; numbers are numbers; `echo` and
+`echo_pool` also take `debug`. A value that does not read raises `InvalidArgumentError` naming the
+option, failing the service that needed the URL. Only the connection's own URL is read this way,
+never a replica's.
+
+## Read replicas
+
+```python
+ConnectionConfig(
+    url=env("DATABASE_URL"),
+    replicas={"replica1": env("DATABASE_REPLICA_URL"), "replica2": env("DATABASE_REPLICA2_URL")},
+    keep_replica=False,
+)
+```
+
+- A session reads from a replica picked at random.
+- It goes to the primary for a write, for a transaction's statements, and for every read after
+  them, so it sees what it wrote.
+- It stays on the primary for the rest of its unit of work, unless `keep_replica=True` sends it
+  back to the replicas once it commits.
+- Each unit of work starts on the replicas, whatever the one before wrote.
+- Migrations and the `orm:database:*` commands always use the primary.
+- The injected session maker is a `RoutingAsyncSessionMaker` instead of an `async_sessionmaker`.
+- Send one block elsewhere with `primary_context()` / `replica_context()` from
+  `advanced_alchemy.routing`.
+
+## Without a container
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from xtr_orm import ConnectionRegistry, DatabaseManager, MigrationsConfig, Migrator
+
+url = "sqlite+aiosqlite:///shop.db"
+engine = create_async_engine(url)
+
+registry = ConnectionRegistry()  # ConnectionRegistry(default="primary") renames the default
+registry.register(
+    "default",
+    engine=engine,
+    migrator=Migrator(engine, MigrationsConfig(directory="migrations", render_as_batch=True)),
+    database=DatabaseManager(url),
+    session=None,  # an async callable returning the unit of work's session; the middleware need it
+    close=None,  # an async callable; the engine is disposed when left out
+    in_use=None,  # a callable; the connection always counts as in use when left out
+)
+
+await registry.engine()  # the default connection's
+await registry.migrator("reports")
+registry.names(), registry.in_use(), registry.has("reports"), registry.default
+await registry.close()
+```
+
+Each of `engine`, `migrator` and `database` takes the object itself or an async function building
+it, called only when that piece is first asked for. `DEFAULT_CONNECTION` (`"default"`) is exported
+from `xtr_orm`.

xtr_orm-3.0.0/src/xtr_orm/.agents/skills/xtr-orm/references/messenger.md

@@ -0,0 +1,95 @@
+# Message bus middleware
+
+Needs the `messenger` extra: `uv add "xtr-orm[messenger]"`. With both bundles active, importing
+`xtr_orm.messenger` is done for you and each middleware is registered under its name for a bus
+configuration to list.
+
+| Name | Class | Does | Arguments |
+|---|---|---|---|
+| `orm_transaction` | `TransactionMiddleware` | Runs every handler of a message in one transaction, committed once they all succeeded and rolled back otherwise. A failure drops the other handlers' handled stamps, so a retry runs them all again | `connection_name`, the default connection when left out |
+| `orm_close_connection` | `CloseConnectionMiddleware` | Closes the connections once a worker handled a message it consumed, so an idle worker holds none — once the last, when it handles several at once | `connection_names`, every connection in use when left out |
+| `orm_open_transaction_logger` | `OpenTransactionLoggerMiddleware` | Logs an error when a handler began a transaction (`begin()`, `begin_nested()`) and left it open in a message that was handled | `connection_names`, as above |
+
+"In use" means a connection whose engine has been built; opening one to find out would read its
+configuration, so an untouched connection is left alone.
+
+## Order
+
+```python
+# <app>/config/messenger.py
+MessageBusConfig(
+    middleware=[
+        "orm_close_connection",
+        "orm_transaction",
+        {"orm_transaction": {"connection_name": "reports"}},
+        "orm_open_transaction_logger",
+    ],
+)
+```
+
+- `orm_close_connection` outermost, so it closes after the transaction ended.
+- `orm_open_transaction_logger` inside `orm_transaction`, so it looks before the commit closes
+  everything.
+- A second `orm_transaction` with another `connection_name` puts that connection in a transaction
+  too.
+
+## Handlers
+
+```python
+# app/billing/handlers.py
+@as_message_handler(IssueInvoice)
+async def issue(message: IssueInvoice, session: Injected[AsyncSession]) -> None:
+    session.add(Invoice(order_id=message.order_id))  # no commit
+
+
+@as_message_handler(IssueInvoice)
+class NotifyAccounting:
+    # A scoped repository on the same session: one transaction for both handlers.
+    async def __call__(
+        self, message: IssueInvoice, invoices: Injected[InvoiceRepository]
+    ) -> None: ...
+```
+
+- **One session per message.** Every handler of the message, and every scoped service built on the
+  session, gets the same one, released once the message is done with.
+- **A nested dispatch joins the unit of work** and its transaction, in a savepoint of its own: when
+  it fails only its handlers' work is rolled back, and the handler that dispatched it decides
+  whether the rest goes on.
+- **Handlers do not commit.** One that does ends the transaction early; one using
+  `async with session.begin()` is refused, the transaction being open already.
+- **Follow-ups wait for the commit only when stamped.** A message dispatched to a transport is
+  sent at once, before the commit and whether or not it comes:
+
+  ```python
+  await bus.dispatch(SendReceipt(order.id), DispatchAfterCurrentBusStamp())
+  ```
+
+  With that stamp it goes out only once the message being handled was committed, and never after a
+  rollback.
+- **Only messages a worker consumed** — one carrying a `ReceivedStamp` on arrival — close
+  connections afterwards. A message handled during its dispatch, `sync://` included, closes
+  nothing. A worker handling several at once closes once the last is done.
+- **A dropped connection** is found by the engine option `pool_pre_ping` as a connection is taken
+  from the pool (`?pool_pre_ping=true` on a worker's URL), so there is no middleware for it.
+
+## Without a container
+
+Build the middleware yourself and put the instances in the bus configuration. They need a
+`ConnectionRegistry` whose connections were registered with a `session` callable — what returns the
+session the handlers use — or `registry.session()` raises `SessionUnavailableError`.
+
+```python
+from xtr_orm.messenger import (
+    CloseConnectionMiddleware,
+    OpenTransactionLoggerMiddleware,
+    TransactionMiddleware,
+)
+
+middleware = [
+    CloseConnectionMiddleware(registry),
+    TransactionMiddleware(registry),
+    OpenTransactionLoggerMiddleware(registry),
+]
+```
+
+`connection_names` takes one name or a sequence of them.

xtr_orm-3.0.0/src/xtr_orm/.agents/skills/xtr-orm/references/migrations.md

@@ -0,0 +1,71 @@
+# MigrationsConfig and revision templates
+
+A frozen dataclass; every field has a default, so `MigrationsConfig()` is valid.
+Import it from `xtr_orm` or from `xtr_orm.bundle`.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `directory` | `"migrations"` | Where revision files are read and written. A relative path is relative to the working directory — under a kernel start it with `%kernel.project_dir%` |
+| `version_table` | `"alembic_version"` | Holds the revisions the database is at |
+| `history_table` | `"alembic_version_history"` | A row per revision ever applied: `version`, `executed_at`, `execution_time` in milliseconds |
+| `version_table_schema` | `None` | The schema of both; the connection's default when `None` |
+| `file_template` | `"{year}{month}{day}{hour}{minute}{second}_{rev}_{slug}"` | How a file is named; `{epoch}` is available too |
+| `truncate_slug_length` | `40` | The longest message part of a file name |
+| `timezone` | `None` | The zone a revision's date is written in |
+| `template_directory` | `None` | A directory holding a `script.py.mako` to render new revisions from |
+| `recursive_version_locations` | `False` | Read subdirectories of `directory` too |
+| `post_write_hooks` | `()` | Programs run on each file written, such as a formatter |
+| `transaction_per_migration` | `False` | Commit after each revision rather than once |
+| `transactional_ddl` | `None` | Run schema changes inside the transaction |
+| `compare_type` | `False` | Compare column types in a diff |
+| `compare_server_default` | `False` | Compare server defaults in a diff |
+| `render_as_batch` | `False` | Write table changes as batches. **SQLite needs this** |
+| `include_schemas` | `False` | Read other schemas in a diff |
+| `include_name` / `include_object` | `None` | Callables deciding what a diff reads |
+| `render_item` | `None` | Callable deciding how an item is written |
+| `process_revision_directives` | `None` | Callable adjusting a diff before it is written |
+| `user_module_prefix` | `None` | The prefix custom column types are written with |
+| `context_options` | `{}` | Any other migration context option, passed through |
+
+## Custom column types in a diff
+
+A custom type is written under its own module's name, and the revision imports that module:
+`advanced_alchemy.types.guid.GUID(length=16)` plus `import advanced_alchemy.types.guid`. Set
+`user_module_prefix` or `render_item` to write it otherwise.
+
+`compare_type` is off by default on purpose: a type the database stores as another — a UUID kept
+as bytes on SQLite — would otherwise differ in every diff.
+
+## Your own revision template
+
+New revisions render from `script.py.mako`: the package's own, or the one in
+`template_directory`. Nothing else is read from that directory.
+
+The template receives `message`, `up_revision`, `down_revision`, `branch_labels`, `depends_on`,
+`create_date`, `imports`, `upgrades`, `downgrades`, and the `comma` filter
+(`${down_revision | comma,n}`). A template written for a plain migration-runner project works as
+it is.
+
+```python
+MigrationsConfig(
+    template_directory="%kernel.project_dir%/resources/migrations",
+    user_module_prefix="sa.",  # for a template aliasing sa.GUID = GUID
+)
+```
+
+A template calling `op.get_context().autocommit_block()` commits the revision's schema changes
+before the version and history tables are written, and gives up the transaction a failing
+revision would roll back. Set `transaction_per_migration=True` alongside it, and keep it to the
+revisions that need it (`CREATE INDEX CONCURRENTLY`).
+
+## Result objects
+
+| Type | Fields |
+|---|---|
+| `MigrationPlan` | `version`, `direction: Direction`, `description` |
+| `ExecutionResult` | `version`, `direction: Direction`, `duration` in seconds |
+| `AvailableMigration` | `version`, `description`, `down_versions`, `path`, `is_head` |
+| `ExecutedMigration` | the recorded row: its version and when it ran |
+| `MigrationStatus` | `current`, `latest`, `previous`, `next`, `available`, `executed`, `new`, `executed_unavailable`, `is_up_to_date` |
+
+`Direction` is an `Enum` with `Direction.UP` and `Direction.DOWN`.

{xtr_orm-2.0.0 → xtr_orm-3.0.0}/src/xtr_orm/bundle/orm_bundle.py

@@ -105,25 +105,30 @@ class OrmBundle(Bundle[OrmConfig]):
         builder: ContainerBuilder,
     ) -> None:
         """Register every connection's services under its name, the registry, the commands."""
-        for name, spec in config.connections.items():
+        for name, connection in config.connections.items():
             maker_type: type = (
-                RoutingAsyncSessionMaker if spec.replicas else async_sessionmaker[AsyncSession]
+                RoutingAsyncSessionMaker
+                if connection.replicas
+                else async_sessionmaker[AsyncSession]
             )
             factories = (
-                (_alchemy_factory(name, spec), "alchemy"),
+                (_alchemy_factory(name, connection), "alchemy"),
                 (_engine_factory(name), "engine"),
                 (
-                    _routing_maker_factory(name) if spec.replicas else _session_maker_factory(name),
+                    _routing_maker_factory(name)
+                    if connection.replicas
+                    else _session_maker_factory(name),
                     "session_maker",
                 ),
-                (_migrator_factory(name, spec), "migrator"),
-                (_database_factory(spec), "database"),
+                (_migrator_factory(name, connection), "migrator"),
+                (_database_factory(connection), "database"),
             )
             for factory, kind in factories:
                 _ = services.set(named_factory(factory, f"orm_{kind}_{name}"), qualifier=name)
             _ = services.set(
                 named_factory(
-                    _session_factory(name, routed=bool(spec.replicas)), f"orm_session_{name}"
+                    _session_factory(name, routed=bool(connection.replicas)),
+                    f"orm_session_{name}",
                 ),
                 qualifier=name,
                 lifetime="scoped",
@@ -133,7 +138,9 @@ class OrmBundle(Bundle[OrmConfig]):
                     services.alias(service, service, target_qualifier=name)
 
         _ = services.set(_ConnectionsInUse)
-        routed = {name: bool(spec.replicas) for name, spec in config.connections.items()}
+        routed = {
+            name: bool(connection.replicas) for name, connection in config.connections.items()
+        }
         _ = services.set(_connection_registry_factory(config.default_connection, routed))
 
         if bundle_active(builder, "console"):
@@ -165,24 +172,24 @@ def _alchemy_factory(
     """
 
     async def alchemy(in_use: _ConnectionsInUse) -> AsyncIterator[SQLAlchemyAsyncConfig]:
-        spec = connection.with_url_options()
+        resolved = connection.with_url_options()
         # The options are forwarded by name, each checked against the target's
         # fields by ConnectionConfig; their values are the application's.
-        engine = cast("Callable[..., EngineConfig]", EngineConfig)(**spec.engine_options)
+        engine = cast("Callable[..., EngineConfig]", EngineConfig)(**resolved.engine_options)
         session = cast("Callable[..., AsyncSessionConfig]", AsyncSessionConfig)(
-            **spec.session_options
+            **resolved.session_options
         )
         built = cast("Callable[..., SQLAlchemyAsyncConfig]", SQLAlchemyAsyncConfig)(
             # With replicas, the primary is given through the routing instead.
-            connection_string=None if spec.replicas else spec.url,
-            routing_config=_routing(spec) if spec.replicas else None,
+            connection_string=None if resolved.replicas else resolved.url,
+            routing_config=_routing(resolved) if resolved.replicas else None,
             engine_config=engine,
             session_config=session,
-            bind_key=spec.bind_key,
-            **spec.alchemy_options,
+            bind_key=resolved.bind_key,
+            **resolved.alchemy_options,
         )
         routing_maker: RoutingAsyncSessionMaker | None = None
-        if spec.replicas:
+        if resolved.replicas:
             routing_maker = cast("RoutingAsyncSessionMaker", built.create_session_maker())
             # One pool on the primary: the routing's, which migrations use too.
             built.engine_instance = routing_maker.primary_engine
@@ -198,7 +205,7 @@ def _alchemy_factory(
     return alchemy
 
 
-def _routing(spec: ConnectionConfig) -> RoutingConfig:
+def _routing(connection: ConnectionConfig) -> RoutingConfig:
     """Map the connection's replicas onto the database layer's read/write routing.
 
     Reads go to a replica picked at random; a write, a transaction and every
@@ -207,14 +214,14 @@ def _routing(spec: ConnectionConfig) -> RoutingConfig:
     built.
     """
     return RoutingConfig(
-        primary_connection_string=spec.url,
+        primary_connection_string=connection.url,
         read_replicas=[
             ReplicaEngine(connection_string=url, name=replica)
-            for replica, url in spec.replicas.items()
+            for replica, url in connection.replicas.items()
         ],
         routing_strategy=RoutingStrategy.RANDOM,
         sticky_after_write=True,
-        reset_stickiness_on_commit=spec.keep_replica,
+        reset_stickiness_on_commit=connection.keep_replica,
     )
 
 
@@ -281,13 +288,15 @@ def _migrator_factory(
     """Build the factory of the connection ``name``'s migrator, logging to ``orm`` when it can."""
 
     async def migrator(container: ContainerInterface) -> Migrator:
-        spec = connection.with_url_options()
+        resolved = connection.with_url_options()
         metadata = (
-            spec.metadata if spec.metadata is not None else metadata_registry.get(spec.bind_key)
+            resolved.metadata
+            if resolved.metadata is not None
+            else metadata_registry.get(resolved.bind_key)
         )
         built = Migrator(
             await container.get(AsyncEngine, name),
-            spec.migrations or MigrationsConfig(),
+            resolved.migrations or MigrationsConfig(),
             metadata,
             name=name,
         )
@@ -303,10 +312,10 @@ def _database_factory(connection: ConnectionConfig) -> Callable[[], DatabaseMana
     """Build the factory of ``connection``'s database manager."""
 
     def database() -> DatabaseManager:
-        spec = connection.with_url_options()
-        connect_args = spec.engine_options.get("connect_args")
+        resolved = connection.with_url_options()
+        connect_args = resolved.engine_options.get("connect_args")
         return DatabaseManager(
-            spec.url,
+            resolved.url,
             connect_args=connect_args if isinstance(connect_args, dict) else None,  # pyright: ignore[reportUnknownArgumentType] -- an option mapping, read as given
         )
 

xtr_orm-3.0.0/src/xtr_orm/recipe/__init__.py

@@ -0,0 +1,15 @@
+"""This directory holds the package's recipe: its manifest and its templates.
+
+The recipe is what *Use in an application* in the README lists, written as
+data: the bundle to list, the environment variable to declare, and the steps
+only a person can take. An application applies it with
+``xtr-recipes recipes:sync``, which finds this module through the
+``xtr_recipes`` entry point.
+
+Nothing is importable from here. The manifest is read as a file, so a recipe
+is the same from a wheel as from a working tree.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_orm-3.0.0/src/xtr_orm/recipe/files/config/orm.py.tmpl

@@ -0,0 +1,24 @@
+"""The database: one connection, its URL read from ``DATABASE_URL``.
+
+The URL is read when a connection is first used — an engine, a session, a migrator or a
+command — not when the application boots, and its query may carry engine and session
+options. Revisions live in ``migrations/`` in the project directory. Add replicas, more
+connections or the metadata of your own models here.
+"""
+
+from __future__ import annotations
+
+from xtr_dependency_injection import configure, env
+from xtr_orm.bundle import ConnectionConfig, OrmConfig
+
+__all__ = ["orm"]
+
+
+@configure
+def orm() -> OrmConfig:
+    """The ``default`` connection, on ``DATABASE_URL``."""
+    return OrmConfig(
+        connections={
+            "default": ConnectionConfig(url=env("DATABASE_URL")),
+        },
+    )

xtr_orm-3.0.0/src/xtr_orm/recipe/manifest.toml

@@ -0,0 +1,32 @@
+# The recipe for xtr-orm: what *Use in an application* in the README takes, as
+# data. Keep the two in step — the README is the source.
+
+[bundles]
+# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
+"xtr_orm.bundle:OrmBundle" = { all = true }
+
+[files]
+# Destination under the application package = template under this recipe.
+# The default connection on DATABASE_URL, written out so the application has
+# one place to add replicas, connections and its models' metadata.
+"config/orm.py" = "files/config/orm.py.tmpl"
+
+[env]
+# Read when a connection is first used — engine, session, migrator or command —
+# not when the application boots. A local PostgreSQL to start from, for the
+# postgres extra the README installs; change it, or put the real one in
+# .env.local.
+DATABASE_URL = "postgresql+asyncpg://app:change-me@127.0.0.1:5432/app"
+
+[gitignore]
+# Nothing: migrations/ is committed.
+lines = []
+
+[notes]
+steps = [
+  "With the messenger bundle active, list the orm_* middleware in every bus's middleware: every message is then a unit of work.",
+]
+check = [
+  "<script> debug:bundles — orm is listed and active",
+  "<script> orm:migrations:status — it reaches the database",
+]