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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-orm
-Version: 1.5.0
+Version: 2.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>=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: 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}` |
@@ -406,8 +406,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 +463,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-2.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}` |
@@ -367,8 +367,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 +424,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-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "1.5.0"
+version = "2.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>=2.0,<3",
 ]
 
 [[project.authors]]
@@ -42,11 +42,11 @@ 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>=2.0,<3",
+    "xtr-service-contracts>=2.0,<3",
 ]
-console = ["xtr-console>=1.0,<2"]
-messenger = ["xtr-messenger>=1.0,<2"]
+console = ["xtr-console>=2.0,<3"]
+messenger = ["xtr-messenger>=2.0,<3"]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 orm = "xtr_orm.bundle:OrmBundle"
@@ -60,11 +60,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>=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",
 ]
 
 [build-system]

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

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "1.5.0"
+version = "2.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>=2.0,<3",
 ]
 
 [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>=2.0,<3",
+    "xtr-service-contracts>=2.0,<3",
 ]
 console = [
-    "xtr-console>=1.0,<2",
+    "xtr-console>=2.0,<3",
 ]
 messenger = [
-    "xtr-messenger>=1.0,<2",
+    "xtr-messenger>=2.0,<3",
 ]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
@@ -65,11 +65,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>=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",
 ]
 
 [build-system]

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/bundle/connection_config.py

@@ -118,7 +118,9 @@ class ConnectionConfig:
         replicas={"replica1": env("DATABASE_REPLICA_URL")},
         engine_options={"pool_size": 10, "pool_pre_ping": True},
         session_options={"expire_on_commit": False},
-        migrations=MigrationsConfig(render_as_batch=True),
+        migrations=MigrationsConfig(
+            directory="%kernel.project_dir%/migrations", render_as_batch=True
+        ),
     )
     ```
 

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

@@ -28,6 +28,8 @@ Nothing connects until a service is first used, and a URL given as
 from __future__ import annotations
 
 from collections.abc import AsyncIterator, Awaitable, Callable
+from functools import partial
+from operator import contains
 from typing import Final, TypeVar, cast, final
 
 from advanced_alchemy.base import metadata_registry
@@ -88,7 +90,7 @@ class OrmBundle(Bundle[OrmConfig]):
         if not bundle_active(builder, "logging"):
             return
         # Logging is an optional peer, importable only once it is active.
-        from xtr_logging.bundle import LoggingConfig  # noqa: PLC0415
+        from xtr_logging.bundle import LoggingConfig  # noqa: PLC0415 — optional peer
 
         def add_orm_channel(config: LoggingConfig) -> LoggingConfig:
             return config.with_channels(ORM_CHANNEL)
@@ -108,19 +110,21 @@ class OrmBundle(Bundle[OrmConfig]):
                 RoutingAsyncSessionMaker if spec.replicas else async_sessionmaker[AsyncSession]
             )
             factories = (
-                (_alchemy_factory(name), "alchemy"),
+                (_alchemy_factory(name, spec), "alchemy"),
                 (_engine_factory(name), "engine"),
                 (
                     _routing_maker_factory(name) if spec.replicas else _session_maker_factory(name),
                     "session_maker",
                 ),
-                (_migrator_factory(name), "migrator"),
-                (_database_factory(name), "database"),
+                (_migrator_factory(name, spec), "migrator"),
+                (_database_factory(spec), "database"),
             )
             for factory, kind in factories:
                 _ = services.set(named_factory(factory, f"orm_{kind}_{name}"), qualifier=name)
             _ = services.set(
-                named_factory(_session_factory(name), f"orm_session_{name}"),
+                named_factory(
+                    _session_factory(name, routed=bool(spec.replicas)), f"orm_session_{name}"
+                ),
                 qualifier=name,
                 lifetime="scoped",
             )
@@ -128,7 +132,9 @@ class OrmBundle(Bundle[OrmConfig]):
                 for service in (*_PER_CONNECTION, maker_type):
                     services.alias(service, service, target_qualifier=name)
 
-        _ = services.set(_connection_registry)
+        _ = services.set(_ConnectionsInUse)
+        routed = {name: bool(spec.replicas) for name, spec in config.connections.items()}
+        _ = services.set(_connection_registry_factory(config.default_connection, routed))
 
         if bundle_active(builder, "console"):
             services.load("xtr_orm.command")
@@ -136,19 +142,30 @@ class OrmBundle(Bundle[OrmConfig]):
             services.load("xtr_orm.messenger")
 
 
+@final
+class _ConnectionsInUse:
+    """The connections whose database layer — and so engines — the container has built."""
+
+    __slots__ = ("names",)
+
+    def __init__(self) -> None:
+        self.names: set[str] = set()
+
+
 def _alchemy_factory(
-    name: str,
-) -> Callable[[OrmConfig], AsyncIterator[SQLAlchemyAsyncConfig]]:
+    name: str, connection: ConnectionConfig
+) -> Callable[[_ConnectionsInUse], AsyncIterator[SQLAlchemyAsyncConfig]]:
     """Build the factory of the connection ``name``'s database layer configuration.
 
     It owns every engine of the connection — the primary's, and each
-    replica's — and disposes them when the container closes. It injects the
-    configuration rather than closing over it: the container hands it a copy
-    with every environment placeholder resolved.
+    replica's — and disposes them when the container closes. Like every
+    per-connection factory, it closes over its own connection's
+    configuration: the container resolves the environment placeholders of
+    that one alone, so a connection never reads another's variables.
     """
 
-    async def alchemy(config: OrmConfig) -> AsyncIterator[SQLAlchemyAsyncConfig]:
-        spec = config.connections[name].with_url_options()
+    async def alchemy(in_use: _ConnectionsInUse) -> AsyncIterator[SQLAlchemyAsyncConfig]:
+        spec = 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)
@@ -169,6 +186,7 @@ def _alchemy_factory(
             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
+        in_use.names.add(name)
         try:
             yield built
         finally:
@@ -234,22 +252,19 @@ def _routing_maker_factory(
 
 
 def _session_factory(
-    name: str,
-) -> Callable[[OrmConfig, ContainerInterface], AsyncIterator[AsyncSession]]:
+    name: str, *, routed: bool
+) -> Callable[[ContainerInterface], AsyncIterator[AsyncSession]]:
     """Build the factory of the connection ``name``'s session, closed when its unit ends.
 
     Closing rolls back what was not committed: committing is the unit's job.
-    With replicas, a unit starts reading from them whatever the unit before
-    it wrote: sticking to the primary after a write is one unit's state.
+    With replicas — ``routed`` — a unit starts reading from them whatever the
+    unit before it wrote: sticking to the primary after a write is one unit's
+    state, forgotten when the unit ends — not when another of its sessions
+    opens, which would send the reads after a write to a replica.
     """
 
-    async def session(
-        config: OrmConfig, container: ContainerInterface
-    ) -> AsyncIterator[AsyncSession]:
-        routed = bool(config.connections[name].replicas)
+    async def session(container: ContainerInterface) -> AsyncIterator[AsyncSession]:
         maker = (await container.get(SQLAlchemyAsyncConfig, name)).create_session_maker()
-        if routed:
-            _ = stick_to_primary_var.set(False)
         try:
             async with maker() as opened:
                 yield opened
@@ -260,11 +275,13 @@ def _session_factory(
     return session
 
 
-def _migrator_factory(name: str) -> Callable[[OrmConfig, ContainerInterface], Awaitable[Migrator]]:
+def _migrator_factory(
+    name: str, connection: ConnectionConfig
+) -> Callable[[ContainerInterface], Awaitable[Migrator]]:
     """Build the factory of the connection ``name``'s migrator, logging to ``orm`` when it can."""
 
-    async def migrator(config: OrmConfig, container: ContainerInterface) -> Migrator:
-        spec = config.connections[name].with_url_options()
+    async def migrator(container: ContainerInterface) -> Migrator:
+        spec = connection.with_url_options()
         metadata = (
             spec.metadata if spec.metadata is not None else metadata_registry.get(spec.bind_key)
         )
@@ -282,11 +299,11 @@ def _migrator_factory(name: str) -> Callable[[OrmConfig, ContainerInterface], Aw
     return migrator
 
 
-def _database_factory(name: str) -> Callable[[OrmConfig], DatabaseManager]:
-    """Build the factory of the connection ``name``'s database manager."""
+def _database_factory(connection: ConnectionConfig) -> Callable[[], DatabaseManager]:
+    """Build the factory of ``connection``'s database manager."""
 
-    def database(config: OrmConfig) -> DatabaseManager:
-        spec: ConnectionConfig = config.connections[name].with_url_options()
+    def database() -> DatabaseManager:
+        spec = connection.with_url_options()
         connect_args = spec.engine_options.get("connect_args")
         return DatabaseManager(
             spec.url,
@@ -296,23 +313,34 @@ def _database_factory(name: str) -> Callable[[OrmConfig], DatabaseManager]:
     return database
 
 
-def _connection_registry(config: OrmConfig, container: ContainerInterface) -> ConnectionRegistry:
-    """Name every connection for the commands and middleware, each piece built only when needed.
+def _connection_registry_factory(
+    default: str, routed: dict[str, bool]
+) -> Callable[[ContainerInterface, _ConnectionsInUse], ConnectionRegistry]:
+    """Build the factory of the registry of every connection — each ``routed`` or not, by name."""
+
+    def connection_registry(
+        container: ContainerInterface, in_use: _ConnectionsInUse
+    ) -> ConnectionRegistry:
+        """Name every connection for the commands and middleware, each piece built when needed.
+
+        A connection's session is the one of the unit of work under way,
+        closing it disposes every engine it has — its replicas' too — and it
+        is in use once the container built its engines.
+        """
+        registry = ConnectionRegistry(default)
+        for name, replicated in routed.items():
+            registry.register(
+                name,
+                engine=_provider(container, AsyncEngine, name),
+                migrator=_provider(container, Migrator, name),
+                database=_provider(container, DatabaseManager, name),
+                session=_unit_session(name),
+                close=_closer(container, name, routed=replicated),
+                in_use=partial(contains, in_use.names, name),
+            )
+        return registry
 
-    A connection's session is the one of the unit of work under way, and
-    closing it disposes every engine it has — its replicas' too.
-    """
-    registry = ConnectionRegistry(config.default_connection)
-    for name, spec in config.connections.items():
-        registry.register(
-            name,
-            engine=_provider(container, AsyncEngine, name),
-            migrator=_provider(container, Migrator, name),
-            database=_provider(container, DatabaseManager, name),
-            session=_unit_session(name),
-            close=_closer(container, name, routed=bool(spec.replicas)),
-        )
-    return registry
+    return connection_registry
 
 
 def _unit_session(name: str) -> Callable[[], Awaitable[AsyncSession]]:

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/connection_command.py

@@ -95,13 +95,21 @@ def report_results(io: ConsoleStyle, results: Sequence[ExecutionResult]) -> None
         io.text(f"  {verb} {escape(result.version)} ({result.duration:.3f}s)")
 
 
-def save_sql(io: ConsoleStyle, target: str, sql: str) -> None:
-    """Write ``sql`` to ``target`` — a file, or a directory to put a dated file in."""
+def save_sql(io: ConsoleStyle, target: str, sql: str) -> bool:
+    """Write ``sql`` to ``target`` — a file, or a directory to put a dated file in.
+
+    Returns whether it was written; when not, ``io`` says why.
+    """
     path = Path(target)
     if path.is_dir():
         path /= f"migration_{datetime.now().astimezone():%Y%m%d%H%M%S}.sql"
-    _ = path.write_text(sql, encoding="utf-8")
+    try:
+        _ = path.write_text(sql, encoding="utf-8")
+    except OSError as error:
+        io.error(f'Could not write the migration SQL to "{escape(str(path))}": {error.strerror}')
+        return False
     io.success(f'Wrote the migration SQL to "{escape(str(path))}".')
+    return True
 
 
 def report_written(
@@ -125,6 +133,13 @@ def report_count(io: ConsoleStyle, results: Sequence[ExecutionResult]) -> None:
     io.success(f"{len(results)} migration{plural} executed in {total:.3f}s.")
 
 
+def without_a_file(count: int) -> str:
+    """Say how many applied revisions have no revision file."""
+    if count == 1:
+        return "1 applied revision has no revision file."
+    return f"{count} applied revisions have no revision file."
+
+
 def format_version(version: str, description: str | None) -> str:
     """Render a version with its description, as the listing commands show it."""
     return f"{version}{_described(description)}"

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/database_create_command.py

@@ -17,7 +17,7 @@ __all__ = ["DatabaseCreateCommand"]
 @as_command("orm:database:create")
 @final
 class DatabaseCreateCommand(ConnectionCommand):
-    """Creates the configured database."""
+    """Creates a connection's database on its server."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/database_drop_command.py

@@ -17,7 +17,7 @@ __all__ = ["DatabaseDropCommand"]
 @as_command("orm:database:drop")
 @final
 class DatabaseDropCommand(ConnectionCommand):
-    """Drops the configured database."""
+    """Drops a connection's database from its server."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_current_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsCurrentCommand"]
 @as_command("orm:migrations:current")
 @final
 class MigrationsCurrentCommand(ConnectionCommand):
-    """Outputs the current version."""
+    """Prints the revisions the database is at."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_diff_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsDiffCommand"]
 @as_command("orm:migrations:diff")
 @final
 class MigrationsDiffCommand(ConnectionCommand):
-    """Generate a migration by comparing your current database to your mapping information."""
+    """Writes a revision of what differs between the database and the table definitions."""
 
     __slots__ = ()
 
@@ -54,7 +54,7 @@ class MigrationsDiffCommand(ConnectionCommand):
             io.error(escape(error.reason))
             return ExitCode.FAILURE
         if written is None:
-            io.error("No changes detected in your mapping information.")
+            io.error("Nothing differs between the database and the table definitions.")
             return ExitCode.FAILURE
-        report_written(io, "Generated new migration class to", written, connection)
+        report_written(io, "Wrote the new revision to", written, connection)
         return ExitCode.SUCCESS

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_dump_schema_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsDumpSchemaCommand"]
 @as_command("orm:migrations:dump-schema")
 @final
 class MigrationsDumpSchemaCommand(ConnectionCommand):
-    """Dump the schema for your database to a migration."""
+    """Writes a first revision creating every table an existing database has."""
 
     __slots__ = ()
 
@@ -50,7 +50,7 @@ class MigrationsDumpSchemaCommand(ConnectionCommand):
         except MigrationError as error:
             io.error(escape(error.reason))
             return ExitCode.FAILURE
-        report_written(io, "Dumped your schema to a new migration class at", written, connection)
+        report_written(io, "Wrote the schema to a new revision at", written, connection)
         option = f" --connection {escape(connection)}" if connection else ""
         io.text(f"To use this as a rollup migration you can use orm:migrations:rollup{option}")
         return ExitCode.SUCCESS

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_execute_command.py

@@ -24,7 +24,7 @@ __all__ = ["MigrationsExecuteCommand"]
 @as_command("orm:migrations:execute")
 @final
 class MigrationsExecuteCommand(ConnectionCommand):
-    """Execute one or more migration versions up or down manually."""
+    """Runs chosen revisions alone, each up or down."""
 
     __slots__ = ()
 
@@ -67,8 +67,8 @@ class MigrationsExecuteCommand(ConnectionCommand):
             return ExitCode.FAILURE
         try:
             if write_sql is not None:
-                save_sql(io, write_sql, await migrator.execute_sql(versions, direction))
-                return ExitCode.SUCCESS
+                saved = save_sql(io, write_sql, await migrator.execute_sql(versions, direction))
+                return ExitCode.SUCCESS if saved else ExitCode.FAILURE
             planned = await migrator.plan_for_versions(versions, direction)
             if dry_run:
                 report_plan(io, planned)

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_generate_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsGenerateCommand"]
 @as_command("orm:migrations:generate")
 @final
 class MigrationsGenerateCommand(ConnectionCommand):
-    """Generate a blank migration class."""
+    """Writes an empty revision to fill in by hand."""
 
     __slots__ = ()
 
@@ -43,5 +43,5 @@ class MigrationsGenerateCommand(ConnectionCommand):
         except MigrationError as error:
             io.error(escape(error.reason))
             return ExitCode.FAILURE
-        report_written(io, "Generated new migration class to", written, connection)
+        report_written(io, "Wrote the new revision to", written, connection)
         return ExitCode.SUCCESS

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_latest_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsLatestCommand"]
 @as_command("orm:migrations:latest")
 @final
 class MigrationsLatestCommand(ConnectionCommand):
-    """Outputs the latest version."""
+    """Prints the revisions no other follows."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_list_command.py

@@ -17,7 +17,7 @@ __all__ = ["MigrationsListCommand"]
 @as_command("orm:migrations:list")
 @final
 class MigrationsListCommand(ConnectionCommand):
-    """Display a list of all available migrations and their status."""
+    """Lists every revision and whether it is applied."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_migrate_command.py

@@ -15,6 +15,7 @@ from .connection_command import (
     report_plan,
     report_results,
     save_sql,
+    without_a_file,
 )
 
 __all__ = ["MigrationsMigrateCommand"]
@@ -25,7 +26,7 @@ _LATEST: Final = frozenset({"latest", "head", "heads"})
 @as_command("orm:migrations:migrate")
 @final
 class MigrationsMigrateCommand(ConnectionCommand):
-    """Execute a migration to a specified version or the latest available version."""
+    """Brings the database to a revision, up or down."""
 
     __slots__ = ()
 
@@ -67,15 +68,12 @@ class MigrationsMigrateCommand(ConnectionCommand):
                     return ExitCode.SUCCESS
                 io.error(
                     f'The version "{escape(version)}" couldn\'t be reached, '
-                    "there are no registered migrations.",
+                    "there are no revision files.",
                 )
                 return ExitCode.FAILURE
             unregistered = len(status.executed_unavailable)
             if unregistered:
-                io.warning(
-                    f"You have {unregistered} previously executed migrations in the database "
-                    "that are not registered migrations.",
-                )
+                io.warning(without_a_file(unregistered))
                 if not io.confirm("Are you sure you wish to continue?", default=True):
                     io.error("Migration cancelled!")
                     return ExitCode.FAILURE
@@ -90,8 +88,8 @@ class MigrationsMigrateCommand(ConnectionCommand):
                 io.success(message)
                 return ExitCode.SUCCESS
             if write_sql is not None:
-                save_sql(io, write_sql, await migrator.migrate_sql(version))
-                return ExitCode.SUCCESS
+                saved = save_sql(io, write_sql, await migrator.migrate_sql(version))
+                return ExitCode.SUCCESS if saved else ExitCode.FAILURE
             if dry_run:
                 report_plan(io, plans)
                 io.note("Dry run: nothing was executed.")

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_rollup_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsRollupCommand"]
 @as_command("orm:migrations:rollup")
 @final
 class MigrationsRollupCommand(ConnectionCommand):
-    """Rollup migrations by deleting all tracked versions and insert the one version that exists."""
+    """Records the single remaining revision as all the database has applied."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_status_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsStatusCommand"]
 @as_command("orm:migrations:status")
 @final
 class MigrationsStatusCommand(ConnectionCommand):
-    """View the status of a set of migrations."""
+    """Shows where the database stands against its revisions."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_up_to_date_command.py

@@ -8,7 +8,7 @@ from xtr_console import ConsoleStyle, ExitCode, Option, as_command, escape
 
 from xtr_orm.exception import MigrationError
 
-from .connection_command import ConnectionCommand
+from .connection_command import ConnectionCommand, without_a_file
 
 __all__ = ["MigrationsUpToDateCommand"]
 
@@ -19,7 +19,7 @@ _UNREGISTERED: Final = 2
 @as_command("orm:migrations:up-to-date")
 @final
 class MigrationsUpToDateCommand(ConnectionCommand):
-    """Tells you if your schema is up-to-date."""
+    """Tells whether every revision is applied."""
 
     __slots__ = ()
 
@@ -62,12 +62,7 @@ class MigrationsUpToDateCommand(ConnectionCommand):
             io.error(f"Out-of-date! {new} migration{are} available to execute.")
             code = ExitCode.FAILURE
         if unregistered:
-            io.error(
-                f"You have {unregistered} previously executed "
-                f"migration{'' if unregistered == 1 else 's'} in the database that "
-                f"{'is not a' if unregistered == 1 else 'are not'} registered "
-                f"migration{'' if unregistered == 1 else 's'}.",
-            )
+            io.error(without_a_file(unregistered))
             if fail_on_unregistered:
                 code = _UNREGISTERED
         if list_migrations:

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/migrations_version_command.py

@@ -16,7 +16,7 @@ __all__ = ["MigrationsVersionCommand"]
 @as_command("orm:migrations:version")
 @final
 class MigrationsVersionCommand(ConnectionCommand):
-    """Manually add and delete migration versions from the version table."""
+    """Records revisions as applied or not, running nothing."""
 
     __slots__ = ()
 
@@ -58,8 +58,9 @@ class MigrationsVersionCommand(ConnectionCommand):
         if migrator is None:
             return ExitCode.FAILURE
         if not io.confirm(
-            "WARNING! You are about to add, delete or synchronize migration versions from the "
-            "version table that could result in data lost. Are you sure you wish to continue?",
+            "WARNING! You are about to record revisions as applied or not without running them, "
+            "which can leave the version table out of step with the schema. Are you sure you "
+            "wish to continue?",
             default=True,
         ):
             io.error("Migration cancelled!")

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/command/run_sql_command.py

@@ -16,7 +16,7 @@ __all__ = ["RunSqlCommand"]
 @as_command("orm:run-sql")
 @final
 class RunSqlCommand(ConnectionCommand):
-    """Executes arbitrary SQL directly from the command line."""
+    """Runs a statement and shows what it returned."""
 
     __slots__ = ()
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/connection_registry.py

@@ -33,6 +33,7 @@ class _Connection:
     database: Callable[[], Awaitable[DatabaseManager]]
     session: Callable[[], Awaitable[AsyncSession]] | None
     close: Callable[[], Awaitable[None]] | None
+    in_use: Callable[[], bool] | None
 
 
 @final
@@ -83,6 +84,7 @@ class ConnectionRegistry:
         database: DatabaseManager | Callable[[], Awaitable[DatabaseManager]],
         session: Callable[[], Awaitable[AsyncSession]] | None = None,
         close: Callable[[], Awaitable[None]] | None = None,
+        in_use: Callable[[], bool] | None = None,
     ) -> None:
         """Add the connection ``name``, or replace it.
 
@@ -95,6 +97,8 @@ class ConnectionRegistry:
                 without it, :meth:`session` is refused.
             close: What closes the connection; its engine is disposed when
                 left out.
+            in_use: Whether the connection is in use — its engine built;
+                without it, the connection always is. See :meth:`in_use`.
 
         Raises:
             InvalidArgumentError: When ``name`` is empty.
@@ -107,12 +111,26 @@ class ConnectionRegistry:
             database=_provider(database, DatabaseManager),
             session=session,
             close=close,
+            in_use=in_use,
         )
 
     def names(self) -> tuple[str, ...]:
         """Every connection's name, in the order registered."""
         return tuple(self._connections)
 
+    def in_use(self) -> tuple[str, ...]:
+        """The names of the connections in use, in the order registered.
+
+        What the message bus middleware act on unless given names: a
+        connection nothing has used has no session to check and no pool to
+        close, and opening it to find out would read its configuration.
+        """
+        return tuple(
+            name
+            for name, connection in self._connections.items()
+            if connection.in_use is None or connection.in_use()
+        )
+
     def has(self, name: str | None = None) -> bool:
         """Whether the connection ``name`` — the default one when ``None`` — exists."""
         return (name or self._default) in self._connections

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/messenger/close_connection_middleware.py

@@ -41,7 +41,7 @@ class CloseConnectionMiddleware(MiddlewareInterface):
         connections: ConnectionRegistry,
         connection_names: str | Sequence[str] = (),
     ) -> None:
-        """Close ``connection_names`` — every connection when none is given."""
+        """Close ``connection_names`` — every connection in use when none is given."""
         self._connections = connections
         self._consumed = 0
         self._connection_names = (
@@ -58,8 +58,7 @@ class CloseConnectionMiddleware(MiddlewareInterface):
         Raises:
             UnknownConnectionError: When a connection named is not registered.
         """
-        names = self._connection_names or self._connections.names()
-        for name in names:
+        for name in self._connection_names:
             if not self._connections.has(name):
                 raise UnknownConnectionError(name, self._connections.names())
         if envelope.last(ReceivedStamp) is None:
@@ -71,5 +70,5 @@ class CloseConnectionMiddleware(MiddlewareInterface):
         finally:
             self._consumed -= 1
             if self._consumed == 0:
-                for name in names:
+                for name in self._connection_names or self._connections.in_use():
                     await self._connections.close(name)

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/messenger/open_transaction_logger_middleware.py

@@ -35,7 +35,8 @@ class OpenTransactionLoggerMiddleware(MiddlewareInterface):
 
     A transaction counts when a handler began it — ``begin()`` or
     ``begin_nested()`` on the unit of work's session — not when the session
-    began one by itself for a query.
+    began one by itself for a query. Only a message that was handled is
+    checked: one that failed leaves its transaction to be rolled back.
     """
 
     __slots__ = ("_connection_names", "_connections", "_logger")
@@ -46,7 +47,7 @@ class OpenTransactionLoggerMiddleware(MiddlewareInterface):
         logger: LoggerInterface = _DISCARD,
         connection_names: str | Sequence[str] = (),
     ) -> None:
-        """Check ``connection_names`` — every connection when none is given — logging to ``logger``.
+        """Check ``connection_names`` — every one in use when none is given — logging to ``logger``.
 
         Under a container, ``logger`` is the application's logger when the
         logging bundle is active; otherwise what is found goes nowhere.
@@ -62,20 +63,27 @@ class OpenTransactionLoggerMiddleware(MiddlewareInterface):
         """Run the rest of the chain, then log each connection left with a transaction open."""
         if _handling.get():
             return await stack.next().handle(envelope, stack)
-        names = self._connection_names or self._connections.names()
-        sessions = {name: await self._connections.session(name) for name in names}
-        initial = {name: _opened(session) for name, session in sessions.items()}
+        initial = {
+            name: _opened(await self._connections.session(name))
+            for name in self._connection_names or self._connections.in_use()
+        }
         token = _handling.set(True)
         try:
-            return await stack.next().handle(envelope, stack)
+            handled = await stack.next().handle(envelope, stack)
         finally:
             _handling.reset(token)
-            left = [name for name, session in sessions.items() if _opened(session) > initial[name]]
-            if left:
-                self._logger.error(
-                    "A handler opened a transaction but did not close it.",
-                    {"connections": left, "message": envelope.message},
-                )
+        # Read again: a connection the handlers put in use is checked too.
+        left = [
+            name
+            for name in self._connection_names or self._connections.in_use()
+            if _opened(await self._connections.session(name)) > initial.get(name, 0)
+        ]
+        if left:
+            self._logger.error(
+                "A handler opened a transaction but did not close it.",
+                {"connections": left, "message": envelope.message},
+            )
+        return handled
 
 
 def _opened(session: AsyncSession) -> int:

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/migrations/_environment.py

@@ -131,7 +131,8 @@ class Environment:
                 "include_name": _include_name(config.include_name, config.history_table),
                 "include_object": config.include_object,
                 "render_item": _render_item(config.render_item, config.user_module_prefix),
-                "process_revision_directives": config.process_revision_directives,
+                # Not "process_revision_directives": the migrator runs it inside its own,
+                # which the runner would call first, before the revision is complete.
                 "user_module_prefix": config.user_module_prefix,
                 "literal_binds": as_sql,
                 "output_buffer": output,

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/migrations/executed_migration.py

@@ -22,7 +22,9 @@ class ExecutedMigration:
 
     Attributes:
         version: The revision's identifier.
-        executed_at: When it was applied, by the database's clock.
+        executed_at: When it was applied, by the database's clock — with a
+            time zone where the column keeps one (PostgreSQL), naive
+            elsewhere: UTC on SQLite, the session's time zone on MySQL.
         execution_time: How long it took, in seconds.
     """
 

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/migrations/migrations_config.py

@@ -50,7 +50,9 @@ class MigrationsConfig:
 
     Attributes:
         directory: Where revision files are read from and written to; created
-            when the first one is written.
+            when the first one is written. A relative path is relative to the
+            working directory — under a kernel, start it with
+            ``%kernel.project_dir%``.
         version_table: The table holding the database's current revisions.
         version_table_schema: The schema of both tables; the connection's
             default when ``None``.

{xtr_orm-1.5.0 → xtr_orm-2.0.0}/src/xtr_orm/migrations/migrator.py

@@ -271,15 +271,21 @@ class Migrator(LoggerAware):
                 f'The "{self._name}" connection has no table definitions to compare with.',
             )
         tables = tables_of(self._metadata) if from_empty_schema else None
+        hook = self._config.process_revision_directives
 
         def adjust(
             context: MigrationContext, revision: object, directives: list[MigrationScript]
         ) -> None:
-            del context, revision
-            script = directives[0]
             if tables is not None:
-                script.upgrade_ops, script.downgrade_ops = creating(tables)
-            if not allow_empty and script.upgrade_ops is not None and script.upgrade_ops.is_empty():
+                directives[0].upgrade_ops, directives[0].downgrade_ops = creating(tables)
+            if hook is not None:
+                hook(context, revision, directives)
+            if (
+                not allow_empty
+                and directives
+                and directives[0].upgrade_ops is not None
+                and directives[0].upgrade_ops.is_empty()
+            ):
                 directives.clear()
 
         def work(connection: Connection) -> AvailableMigration | None:
@@ -341,11 +347,14 @@ class Migrator(LoggerAware):
             if not tables:
                 raise MigrationError("The database schema does not contain any tables.")
 
+            hook = self._config.process_revision_directives
+
             def replace(
                 context: MigrationContext, revision: object, directives: list[MigrationScript]
             ) -> None:
-                del context, revision
                 directives[0].upgrade_ops, directives[0].downgrade_ops = creating(tables)
+                if hook is not None:
+                    hook(context, revision, directives)
 
             context = RevisionContext(
                 Config(),
@@ -603,7 +612,11 @@ class Migrator(LoggerAware):
             else:
                 if revision not in done:
                     raise MigrationError(f'The version "{revision}" is not applied.')
-                followers = sorted(child for child in script.nextrev if child in done)
+                followers = sorted(
+                    each
+                    for each in done
+                    if revision in parents(directory, resolve(directory, each))
+                )
                 if followers:
                     raise MigrationError(
                         f'The version "{revision}" is followed by "{followers[0]}", '