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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-orm
-Version: 1.5.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>=1.0,<2
-Requires-Dist: xtr-console>=1.0,<2 ; extra == 'console'
-Requires-Dist: xtr-dependency-injection>=1.0,<2 ; extra == 'di'
-Requires-Dist: xtr-service-contracts>=1.0,<2 ; extra == 'di'
-Requires-Dist: xtr-messenger>=1.0,<2 ; 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'
@@ -152,7 +152,7 @@ the files, not its schema against your models; `diff` compares those.
 
 | Field | Default | Meaning |
 |---|---|---|
-| `directory` | `"migrations"` | Where revision files are read and written |
+| `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` / `history_table` | `"alembic_version"` / `"alembic_version_history"` | The two tables |
 | `version_table_schema` | `None` | Their schema; the connection's default when `None` |
 | `file_template` | `"{year}{month}{day}{hour}{minute}{second}_{rev}_{slug}"` | How a file is named; also `{epoch}` |
@@ -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
@@ -406,8 +410,8 @@ MessageBusConfig(
 | 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 when left out |
-| `orm_open_transaction_logger` | `OpenTransactionLoggerMiddleware` | Logs an error — to the application's logger when the logging bundle is active — when a handler began a transaction — `begin()`, `begin_nested()` — and left it open | `connection_names`, every 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 — its engine built — when left out |
+| `orm_open_transaction_logger` | `OpenTransactionLoggerMiddleware` | Logs an error — to the application's logger when the logging bundle is active — when a handler began a transaction — `begin()`, `begin_nested()` — and left it open, in a message that was handled | `connection_names`, every connection in use — its engine built — when left out |
 
 - **One session per message.** The messenger bundle makes every message a unit of work, and a
   scoped service — the session, a repository built on it — is the unit's: every handler of
@@ -463,6 +467,11 @@ Every error derives from `OrmError`.
 
 ## Known limitations
 
+- **Migrations take no lock.** Two processes migrating one database at once — two deploys
+  starting together — both run the same revisions; run `orm:migrations:migrate` from one
+  place, before the application starts.
+- **Applied times follow the database.** `executed_at` has a time zone on PostgreSQL and is
+  naive elsewhere: UTC on SQLite, the session's time zone on MySQL.
 - **advanced-alchemy's model registry is process-wide.** Its `metadata_registry` maps a
   `bind_key` to table definitions for the whole process, so two kernels in one process share
   it. Give a connection its `metadata` explicitly to keep a kernel's diff to its own models.

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

@@ -113,7 +113,7 @@ the files, not its schema against your models; `diff` compares those.
 
 | Field | Default | Meaning |
 |---|---|---|
-| `directory` | `"migrations"` | Where revision files are read and written |
+| `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` / `history_table` | `"alembic_version"` / `"alembic_version_history"` | The two tables |
 | `version_table_schema` | `None` | Their schema; the connection's default when `None` |
 | `file_template` | `"{year}{month}{day}{hour}{minute}{second}_{rev}_{slug}"` | How a file is named; also `{epoch}` |
@@ -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
@@ -367,8 +371,8 @@ MessageBusConfig(
 | 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 when left out |
-| `orm_open_transaction_logger` | `OpenTransactionLoggerMiddleware` | Logs an error — to the application's logger when the logging bundle is active — when a handler began a transaction — `begin()`, `begin_nested()` — and left it open | `connection_names`, every 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 — its engine built — when left out |
+| `orm_open_transaction_logger` | `OpenTransactionLoggerMiddleware` | Logs an error — to the application's logger when the logging bundle is active — when a handler began a transaction — `begin()`, `begin_nested()` — and left it open, in a message that was handled | `connection_names`, every connection in use — its engine built — when left out |
 
 - **One session per message.** The messenger bundle makes every message a unit of work, and a
   scoped service — the session, a repository built on it — is the unit's: every handler of
@@ -424,6 +428,11 @@ Every error derives from `OrmError`.
 
 ## Known limitations
 
+- **Migrations take no lock.** Two processes migrating one database at once — two deploys
+  starting together — both run the same revisions; run `orm:migrations:migrate` from one
+  place, before the application starts.
+- **Applied times follow the database.** `executed_at` has a time zone on PostgreSQL and is
+  naive elsewhere: UTC on SQLite, the session's time zone on MySQL.
 - **advanced-alchemy's model registry is process-wide.** Its `metadata_registry` maps a
   `bind_key` to table definitions for the whole process, so two kernels in one process share
   it. Give a connection its `metadata` explicitly to keep a kernel's diff to its own models.

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "1.5.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>=1.0,<2",
+    "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>=1.0,<2",
-    "xtr-service-contracts>=1.0,<2",
+    "xtr-dependency-injection>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
 ]
-console = ["xtr-console>=1.0,<2"]
-messenger = ["xtr-messenger>=1.0,<2"]
+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>=1.0,<2",
-    "xtr-dependency-injection>=1.0,<2",
-    "xtr-logging>=1.0,<2",
-    "xtr-messenger>=1.0,<2",
-    "xtr-service-contracts>=1.0,<2",
+    "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-1.5.0 → xtr_orm-3.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "1.5.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>=1.0,<2",
+    "xtr-logging-contracts>=3.0,<4",
 ]
 
 [project.optional-dependencies]
@@ -40,14 +40,14 @@ mysql = [
     "asyncmy>=0.2.9",
 ]
 di = [
-    "xtr-dependency-injection>=1.0,<2",
-    "xtr-service-contracts>=1.0,<2",
+    "xtr-dependency-injection>=3.0,<4",
+    "xtr-service-contracts>=3.0,<4",
 ]
 console = [
-    "xtr-console>=1.0,<2",
+    "xtr-console>=3.0,<4",
 ]
 messenger = [
-    "xtr-messenger>=1.0,<2",
+    "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>=1.0,<2",
-    "xtr-dependency-injection>=1.0,<2",
-    "xtr-logging>=1.0,<2",
-    "xtr-messenger>=1.0,<2",
-    "xtr-service-contracts>=1.0,<2",
+    "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.