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

{xtr_orm-3.0.0 → xtr_orm-4.0.2}/LICENSE

@@ -1,6 +1,10 @@
 MIT License
 
 Copyright (c) 2026 xterr
+Copyright (c) 2006-2018 Doctrine Project
+Copyright (c) 2011 Fabien Potencier, Doctrine Project
+Copyright (c) 2006-2013 Doctrine Project
+Copyright (c) 2004-present Fabien Potencier
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

xtr_orm-3.0.0/README.md → xtr_orm-4.0.2/PKG-INFO

@@ -1,3 +1,42 @@
+Metadata-Version: 2.4
+Name: xtr-orm
+Version: 4.0.2
+Summary: Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection.
+Keywords: orm,database,migrations,sqlalchemy,alembic,asyncio
+Author: Xterr
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+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>=4.0,<5
+Requires-Dist: xtr-console>=4.0,<5 ; extra == 'console'
+Requires-Dist: xtr-dependency-injection>=4.0,<5 ; extra == 'di'
+Requires-Dist: xtr-service-contracts>=4.0,<5 ; extra == 'di'
+Requires-Dist: xtr-messenger>=4.0,<5 ; extra == 'messenger'
+Requires-Dist: asyncmy>=0.2.9 ; extra == 'mysql'
+Requires-Dist: asyncpg>=0.29 ; extra == 'postgres'
+Requires-Dist: aiosqlite>=0.20 ; extra == 'sqlite'
+Requires-Python: >=3.11
+Provides-Extra: console
+Provides-Extra: di
+Provides-Extra: messenger
+Provides-Extra: mysql
+Provides-Extra: postgres
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 # xtr-orm
@@ -299,6 +338,82 @@ whatever the one before wrote. Migrations and the database commands always use t
 A block can be sent elsewhere with advanced-alchemy's `primary_context()` and
 `replica_context()`, from `advanced_alchemy.routing`.
 
+## Mapping tables from a bundle
+
+A library can bring its own tables to an application's database — tables whose prefix, names
+or column types the application configures, and which therefore exist only once that
+configuration is read. `OrmMappingsPass` puts them into the table definitions of the
+connection the application picked, while the container is compiled: early enough for
+`orm:migrations:diff` to write them like any of the application's own models.
+
+The library's bundle keeps the pass, registers it in `build`, and hands over the driver it
+builds from its configuration in `load_extension`:
+
+```python
+from xtr_orm.bundle import OrmBundle, OrmMappingsPass
+
+
+@final
+@required_bundle(OrmBundle)
+@as_bundle("invoicing", config=InvoicingConfig)
+class InvoicingBundle(Bundle[InvoicingConfig]):
+    def __init__(self) -> None:
+        self._mappings = OrmMappingsPass("invoicing.connection", "invoicing.persist")
+
+    @override
+    def build(self, builder: ContainerBuilder) -> None:
+        builder.add_compiler_pass(self._mappings)
+
+    @override
+    def load_extension(
+        self, config: InvoicingConfig, services: ServiceConfigurator, builder: ContainerBuilder
+    ) -> None:
+        builder.set_parameter("invoicing.connection", config.connection)
+        builder.set_parameter("invoicing.persist", config.persist)
+        if config.persist:
+            self._mappings.set_driver(InvoicingDriver(config.table_prefix))
+```
+
+A driver is anything satisfying `MappingDriverInterface`: one call, adding its tables and
+naming them. Subclass it to have the type checker hold you to that call.
+
+```python
+from xtr_orm import MappingDriverInterface
+
+
+@final
+class InvoicingDriver(MappingDriverInterface):
+    def __init__(self, prefix: str) -> None:
+        self._prefix = prefix
+
+    def load_metadata(self, metadata: MetaData) -> tuple[str, ...]:
+        name = f"{self._prefix}invoice"
+        if name in metadata.tables:
+            return ()
+        _ = Table(name, metadata, Column("id", Integer, primary_key=True))
+        return (name,)
+```
+
+- **Which definitions** — the ones the connection's migrations compare the database with: its
+  `metadata` when it has one, else the ones advanced-alchemy registers for its `bind_key`. A
+  connection keeping several sets is refused, naming it; give that one a single `MetaData`.
+- **Idempotent, always** — `load_metadata` skips the tables already there and leaves them out
+  of what it returns. The registered definitions are process-wide — advanced-alchemy keeps one
+  `MetaData` per bind key for the whole process — so two kernels in one process load the same
+  driver into the same one. That outlives the flag: a kernel built with the library's
+  persistence off maps nothing itself, yet still *sees* every table a persisting kernel of the
+  same process put in that bind key, or in a module-level `MetaData` both reach, and diffs
+  them as its own. Give such a kernel a `bind_key`, or a freshly built `MetaData`, that no
+  persisting kernel used.
+- **On or off** — the flag parameter is read for truth, and an unset one means off, so a
+  library whose persistence an application turned off maps nothing. On with no driver handed
+  over is refused, as is a connection name nothing configured — both naming what is missing.
+- **Read while compiling** — both parameters are read before `%name%` references are resolved
+  and long before an `env(...)` one is, so a bundle sets them from its own resolved
+  configuration: a plain name and a plain flag. One still holding a `%name%` reference is
+  refused, naming the parameter, as is a connection parameter holding something that is not a
+  name at all — a name is never coerced out of it, since a connection may be called `7`.
+
 ## Console commands
 
 Every command takes `--connection NAME`; the default connection's is used without it. The
@@ -324,15 +439,18 @@ commands that change the database ask first; `-n` answers yes.
 
 `--write-sql` writes to the file named, or to a dated file in the directory named.
 
-Without a container, give the commands their connections once:
+Every command takes the `ConnectionRegistry` it acts on as its one constructor argument — the
+bundle's with a container, and your own without one. Nothing stands in for it: a console with no
+container to supply it reports the parameter it cannot fill.
 
 ```python
 from xtr_orm import ConnectionRegistry, DatabaseManager
-from xtr_orm.command import use_connections
+from xtr_orm.command import MigrationsMigrateCommand
 
 registry = ConnectionRegistry()
 registry.register("default", engine=engine, migrator=migrator, database=DatabaseManager(url))
-use_connections(registry)
+
+migrate = MigrationsMigrateCommand(registry)
 ```
 
 ## Message bus middleware
@@ -414,6 +532,11 @@ every statement committed as it runs, and with every connection parameter of the
 database: the credentials, the host and the driver's query options, such as `ssl`. A SQLite
 database is its file. Any other server is refused with `UnsupportedDatabaseError`.
 
+`create` and `drop` let the server refuse a database that is already there or is not, which is
+why both take a flag — `create(if_not_exists=True)`, `drop(if_exists=True)` — to be told so
+instead. On SQLite the file is the database: dropping one that is not there raises
+`MissingDatabaseError`.
+
 ## Errors
 
 Every error derives from `OrmError`.
@@ -422,6 +545,7 @@ Every error derives from `OrmError`.
 |---|---|
 | `InvalidArgumentError` | A configuration cannot be used — an empty name, an unknown option, a URL option that does not read (also a `ValueError`) |
 | `MigrationError` | A migration is refused or its revisions cannot be read — an unknown or ambiguous version, a revision out of order, a diff of a database behind its revisions |
+| `MissingDatabaseError` | A database is dropped that is not there — a SQLite file that does not exist — without `if_exists` (also a `FileNotFoundError`) |
 | `UnknownConnectionError` | A connection is asked for by a name nothing registered (also a `LookupError`) |
 | `UnsupportedDatabaseError` | A database is created or dropped on a server whose statements are not known |
 | `SessionUnavailableError` | A connection's session is asked for outside a unit of work, or of a connection registered without one |

xtr_orm-3.0.0/PKG-INFO → xtr_orm-4.0.2/README.md

@@ -1,42 +1,3 @@
-Metadata-Version: 2.4
-Name: xtr-orm
-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
-Author-email: Xterr <me@xterr.dev>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: AsyncIO
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Database
-Classifier: Typing :: Typed
-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>=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'
-Requires-Python: >=3.11
-Provides-Extra: console
-Provides-Extra: di
-Provides-Extra: messenger
-Provides-Extra: mysql
-Provides-Extra: postgres
-Provides-Extra: sqlite
-Description-Content-Type: text/markdown
-
 <div align="center">
 
 # xtr-orm
@@ -338,6 +299,82 @@ whatever the one before wrote. Migrations and the database commands always use t
 A block can be sent elsewhere with advanced-alchemy's `primary_context()` and
 `replica_context()`, from `advanced_alchemy.routing`.
 
+## Mapping tables from a bundle
+
+A library can bring its own tables to an application's database — tables whose prefix, names
+or column types the application configures, and which therefore exist only once that
+configuration is read. `OrmMappingsPass` puts them into the table definitions of the
+connection the application picked, while the container is compiled: early enough for
+`orm:migrations:diff` to write them like any of the application's own models.
+
+The library's bundle keeps the pass, registers it in `build`, and hands over the driver it
+builds from its configuration in `load_extension`:
+
+```python
+from xtr_orm.bundle import OrmBundle, OrmMappingsPass
+
+
+@final
+@required_bundle(OrmBundle)
+@as_bundle("invoicing", config=InvoicingConfig)
+class InvoicingBundle(Bundle[InvoicingConfig]):
+    def __init__(self) -> None:
+        self._mappings = OrmMappingsPass("invoicing.connection", "invoicing.persist")
+
+    @override
+    def build(self, builder: ContainerBuilder) -> None:
+        builder.add_compiler_pass(self._mappings)
+
+    @override
+    def load_extension(
+        self, config: InvoicingConfig, services: ServiceConfigurator, builder: ContainerBuilder
+    ) -> None:
+        builder.set_parameter("invoicing.connection", config.connection)
+        builder.set_parameter("invoicing.persist", config.persist)
+        if config.persist:
+            self._mappings.set_driver(InvoicingDriver(config.table_prefix))
+```
+
+A driver is anything satisfying `MappingDriverInterface`: one call, adding its tables and
+naming them. Subclass it to have the type checker hold you to that call.
+
+```python
+from xtr_orm import MappingDriverInterface
+
+
+@final
+class InvoicingDriver(MappingDriverInterface):
+    def __init__(self, prefix: str) -> None:
+        self._prefix = prefix
+
+    def load_metadata(self, metadata: MetaData) -> tuple[str, ...]:
+        name = f"{self._prefix}invoice"
+        if name in metadata.tables:
+            return ()
+        _ = Table(name, metadata, Column("id", Integer, primary_key=True))
+        return (name,)
+```
+
+- **Which definitions** — the ones the connection's migrations compare the database with: its
+  `metadata` when it has one, else the ones advanced-alchemy registers for its `bind_key`. A
+  connection keeping several sets is refused, naming it; give that one a single `MetaData`.
+- **Idempotent, always** — `load_metadata` skips the tables already there and leaves them out
+  of what it returns. The registered definitions are process-wide — advanced-alchemy keeps one
+  `MetaData` per bind key for the whole process — so two kernels in one process load the same
+  driver into the same one. That outlives the flag: a kernel built with the library's
+  persistence off maps nothing itself, yet still *sees* every table a persisting kernel of the
+  same process put in that bind key, or in a module-level `MetaData` both reach, and diffs
+  them as its own. Give such a kernel a `bind_key`, or a freshly built `MetaData`, that no
+  persisting kernel used.
+- **On or off** — the flag parameter is read for truth, and an unset one means off, so a
+  library whose persistence an application turned off maps nothing. On with no driver handed
+  over is refused, as is a connection name nothing configured — both naming what is missing.
+- **Read while compiling** — both parameters are read before `%name%` references are resolved
+  and long before an `env(...)` one is, so a bundle sets them from its own resolved
+  configuration: a plain name and a plain flag. One still holding a `%name%` reference is
+  refused, naming the parameter, as is a connection parameter holding something that is not a
+  name at all — a name is never coerced out of it, since a connection may be called `7`.
+
 ## Console commands
 
 Every command takes `--connection NAME`; the default connection's is used without it. The
@@ -363,15 +400,18 @@ commands that change the database ask first; `-n` answers yes.
 
 `--write-sql` writes to the file named, or to a dated file in the directory named.
 
-Without a container, give the commands their connections once:
+Every command takes the `ConnectionRegistry` it acts on as its one constructor argument — the
+bundle's with a container, and your own without one. Nothing stands in for it: a console with no
+container to supply it reports the parameter it cannot fill.
 
 ```python
 from xtr_orm import ConnectionRegistry, DatabaseManager
-from xtr_orm.command import use_connections
+from xtr_orm.command import MigrationsMigrateCommand
 
 registry = ConnectionRegistry()
 registry.register("default", engine=engine, migrator=migrator, database=DatabaseManager(url))
-use_connections(registry)
+
+migrate = MigrationsMigrateCommand(registry)
 ```
 
 ## Message bus middleware
@@ -453,6 +493,11 @@ every statement committed as it runs, and with every connection parameter of the
 database: the credentials, the host and the driver's query options, such as `ssl`. A SQLite
 database is its file. Any other server is refused with `UnsupportedDatabaseError`.
 
+`create` and `drop` let the server refuse a database that is already there or is not, which is
+why both take a flag — `create(if_not_exists=True)`, `drop(if_exists=True)` — to be told so
+instead. On SQLite the file is the database: dropping one that is not there raises
+`MissingDatabaseError`.
+
 ## Errors
 
 Every error derives from `OrmError`.
@@ -461,6 +506,7 @@ Every error derives from `OrmError`.
 |---|---|
 | `InvalidArgumentError` | A configuration cannot be used — an empty name, an unknown option, a URL option that does not read (also a `ValueError`) |
 | `MigrationError` | A migration is refused or its revisions cannot be read — an unknown or ambiguous version, a revision out of order, a diff of a database behind its revisions |
+| `MissingDatabaseError` | A database is dropped that is not there — a SQLite file that does not exist — without `if_exists` (also a `FileNotFoundError`) |
 | `UnknownConnectionError` | A connection is asked for by a name nothing registered (also a `LookupError`) |
 | `UnsupportedDatabaseError` | A database is created or dropped on a server whose statements are not known |
 | `SessionUnavailableError` | A connection's session is asked for outside a unit of work, or of a connection registered without one |

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "3.0.0"
+version = "4.0.2"
 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>=3.0,<4",
+    "xtr-logging-contracts>=4.0,<5",
 ]
 
 [[project.authors]]
@@ -42,11 +42,11 @@ postgres = ["asyncpg>=0.29"]
 sqlite = ["aiosqlite>=0.20"]
 mysql = ["asyncmy>=0.2.9"]
 di = [
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-service-contracts>=3.0,<4",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
-console = ["xtr-console>=3.0,<4"]
-messenger = ["xtr-messenger>=3.0,<4"]
+console = ["xtr-console>=4.0,<5"]
+messenger = ["xtr-messenger>=4.0,<5"]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 orm = "xtr_orm.bundle:OrmBundle"
@@ -63,11 +63,11 @@ dev = [
     "anyio>=4.0",
     "ty>=0.0.83",
     "aiosqlite>=0.20",
-    "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",
+    "xtr-console>=4.0,<5",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-logging>=4.0,<5",
+    "xtr-messenger>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
 
 [build-system]

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "3.0.0"
+version = "4.0.2"
 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>=3.0,<4",
+    "xtr-logging-contracts>=4.0,<5",
 ]
 
 [project.optional-dependencies]
@@ -40,14 +40,14 @@ mysql = [
     "asyncmy>=0.2.9",
 ]
 di = [
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-service-contracts>=3.0,<4",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
 console = [
-    "xtr-console>=3.0,<4",
+    "xtr-console>=4.0,<5",
 ]
 messenger = [
-    "xtr-messenger>=3.0,<4",
+    "xtr-messenger>=4.0,<5",
 ]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
@@ -69,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>=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",
+    "xtr-console>=4.0,<5",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-logging>=4.0,<5",
+    "xtr-messenger>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
 
 [build-system]

{xtr_orm-3.0.0 → xtr_orm-4.0.2}/src/xtr_orm/.agents/skills/xtr-orm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, when a library bundle must add tables it builds in code to a connection's definitions, or when adding OrmBundle to an application on xtr-dependency-injection.
 ---
 
 # xtr-orm
@@ -20,6 +20,8 @@ connection's name. Everything is async; there is no sync counterpart.
 - 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)`.
+- A library bringing its own tables registers an `OrmMappingsPass` from its bundle's `build`; its
+  driver's `load_metadata` must be idempotent.
 - 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.
@@ -114,6 +116,75 @@ under a kernel start it with `%kernel.project_dir%`), `render_as_batch` (SQLite)
 `template_directory`, `user_module_prefix`. See [references/migrations.md](references/migrations.md)
 for every field and for writing your own `script.py.mako`.
 
+## Map tables from a bundle
+
+For a library whose own tables an application configures — their prefix, which of them it keeps,
+which column type an id gets — so they exist only once that configuration is read. Its bundle
+keeps an `OrmMappingsPass`, registers it in `build`, and hands it the driver it builds in
+`load_extension`; the pass loads the tables into the definitions the named connection's
+migrations use, so `orm:migrations:diff` writes them like the application's own models.
+
+```python
+from typing import final
+
+from sqlalchemy import Column, Integer, MetaData, Table
+from typing_extensions import override
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    ServiceConfigurator,
+    as_bundle,
+    required_bundle,
+)
+from xtr_orm import MappingDriverInterface
+from xtr_orm.bundle import OrmBundle, OrmMappingsPass
+
+
+@final
+@required_bundle(OrmBundle)
+@as_bundle("invoicing", config=InvoicingConfig)
+class InvoicingBundle(Bundle[InvoicingConfig]):
+    def __init__(self) -> None:
+        self._mappings = OrmMappingsPass("invoicing.connection", "invoicing.persist")
+
+    @override
+    def build(self, builder: ContainerBuilder) -> None:
+        builder.add_compiler_pass(self._mappings)
+
+    @override
+    def load_extension(
+        self, config: InvoicingConfig, services: ServiceConfigurator, builder: ContainerBuilder
+    ) -> None:
+        builder.set_parameter("invoicing.connection", config.connection)
+        builder.set_parameter("invoicing.persist", config.persist)
+        if config.persist:
+            self._mappings.set_driver(InvoicingDriver(config.table_prefix))
+
+
+@final
+class InvoicingDriver(MappingDriverInterface):
+    def __init__(self, prefix: str) -> None:
+        self._prefix = prefix
+
+    def load_metadata(self, metadata: MetaData) -> tuple[str, ...]:
+        name = f"{self._prefix}invoice"
+        if name in metadata.tables:
+            return ()
+        _ = Table(name, metadata, Column("id", Integer, primary_key=True))
+        return (name,)
+```
+
+A driver is anything satisfying `MappingDriverInterface`: `load_metadata(metadata)` adds its
+tables and returns the names it added. Subclassing it has the type checker hold you to that call.
+
+| Rule | What it means |
+|---|---|
+| Idempotent | Skip every name already in `metadata.tables` and leave it out of the return. The registered definitions are process-wide — one `MetaData` per bind key for the whole process — so a second kernel loads the same driver into the same one. It outlives the flag: a kernel built with persistence off maps nothing itself, yet still sees and diffs every table a persisting kernel of the same process put in that bind key, or in a module-level `MetaData` both reach. Give such a kernel a `bind_key`, or a freshly built `MetaData`, no persisting kernel used |
+| Which definitions | The connection's `metadata` when it has one, else advanced-alchemy's for its `bind_key`. A connection keeping several sets is refused, naming it |
+| On or off | The flag parameter is read for truth; unset means off. On with no driver, or a connection name nothing configured, fails the build with `InvalidArgumentError` |
+| Plain values | Both parameters are read while compiling, before `%name%` is resolved and long before `env(...)` is — set them from the bundle's own resolved config. One still holding a `%name%` reference fails the build naming the parameter, as does a connection parameter holding something that is not a name at all: a name is never coerced out of it, a connection being allowed to be called `7` |
+| Required peer | The bundle must declare `@required_bundle(OrmBundle)`; without it the pass cannot read the orm's configuration and the build fails with `UnknownConfigTypeError` |
+
 ## Console commands
 
 Needs the `console` extra. Every command takes `--connection NAME`, defaulting to
@@ -133,15 +204,18 @@ 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:
+Every command takes the `ConnectionRegistry` it acts on as its one constructor argument. Nothing
+stands in for it: a console with no container to supply it raises `MissingContainerError` naming
+`connections`.
 
 ```python
 from xtr_orm import ConnectionRegistry, DatabaseManager
-from xtr_orm.command import use_connections
+from xtr_orm.command import MigrationsMigrateCommand
 
 registry = ConnectionRegistry()
 registry.register("default", engine=engine, migrator=migrator, database=DatabaseManager(url))
-use_connections(registry)
+
+migrate = MigrationsMigrateCommand(registry)
 ```
 
 ## Use in an application
@@ -251,7 +325,68 @@ 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`.
+is its file. Without `if_exists`, dropping a SQLite file that is not there raises
+`MissingDatabaseError`. Any other server raises `UnsupportedDatabaseError`.
+
+## Testing
+
+Test against a SQLite file in the test's own directory: it is a real database, needs no server,
+and goes away with `tmp_path`. Give a `Migrator` the engine, a `MigrationsConfig` pointing at a
+directory of its own, and your table definitions.
+
+```python
+# tests/test_invoices.py
+from pathlib import Path
+
+import pytest
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import create_async_engine
+from xtr_orm import DatabaseManager, MigrationsConfig, Migrator
+
+from app.models import Base
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+@pytest.mark.anyio
+async def test_the_schema_the_models_describe_is_migrated(tmp_path: Path) -> None:
+    url = f"sqlite+aiosqlite:///{tmp_path / 'app.sqlite'}"
+    assert await DatabaseManager(url).create()
+    engine = create_async_engine(url)
+    migrator = Migrator(
+        engine,
+        # render_as_batch: SQLite cannot alter a table any other way.
+        MigrationsConfig(directory=str(tmp_path / "migrations"), render_as_batch=True),
+        Base.metadata,
+    )
+    try:
+        assert await migrator.diff("the catalogue") is not None
+        _ = await migrator.migrate()
+
+        assert (await migrator.status()).is_up_to_date
+        async with engine.connect() as connection:
+            _ = await connection.execute(text("select count(*) from invoice"))
+    finally:
+        await engine.dispose()
+```
+
+- **A command** takes a `ConnectionRegistry`, so build one for the test and hand it over:
+  `MigrationsStatusCommand(registry)`. Register the connection with the engine, migrator and
+  `DatabaseManager` the test made.
+- **A unit of work** — the scope an `AsyncSession` lives in — is opened by
+  `bind_callable(container, work, per_call_scope=True)` under a kernel; outside one, ask the
+  registry for a session only where you registered one, or `SessionUnavailableError` says so.
+- **Two kernels in one process** share advanced-alchemy's model registry, so give each
+  connection its `metadata` rather than let a diff pick up another test's tables.
+- **A mapping driver** needs no container: `driver.load_metadata(MetaData())` returns the names
+  it added, and a second call on the same `MetaData` must return `()`. A kernel test asserting
+  a library mapped nothing needs a bind key of its own, or an earlier kernel's tables are still
+  in the one it diffs.
+- **Dispose every engine you build**, in a fixture's teardown: an engine left open holds the
+  SQLite file and warns when the loop closes.
 
 ## Errors
 
@@ -261,6 +396,7 @@ Every error derives from `OrmError`.
 |---|---|
 | `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 |
+| `MissingDatabaseError` | A database dropped without `if_exists` is not there — a SQLite file that does not exist. Also a `FileNotFoundError` |
 | `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 |
@@ -279,4 +415,9 @@ Every error derives from `OrmError`.
 - 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 write a mapping driver that defines a table unconditionally: a `load_metadata` that
+  does not skip what is already there fails the second kernel of the process.
+- Do not read turning a library's persistence off as a clean slate: that kernel maps nothing of
+  its own, but still sees and diffs the tables a persisting kernel of the same process left in
+  the bind key — give it a `bind_key`, or a freshly built `MetaData`, no persisting kernel used.
 - Do not expect a timezone on `executed_at` outside PostgreSQL; it is naive elsewhere.