quadkit-sql 0.0.44__tar.gz → 0.0.46__tar.gz

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.5
 Name: quadkit-sql
-Version: 0.0.44
+Version: 0.0.46
 Summary: SQL database abstractions for Quadkit Framework — Postgres, MySQL, SQLite with migrations, repositories, and query building
-Project-URL: Homepage, https://dbtinoy-.github.io/quadkit
+Project-URL: Homepage, https://oridecon.dev
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
-Project-URL: Documentation, https://dbtinoy-.github.io/quadkit
+Project-URL: Documentation, https://oridecon.dev/quadkit/
 Project-URL: Issues, https://github.com/dbtinoy-/quadkit/issues
 Project-URL: Changelog, https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md
-Author-email: Quadkit Framework Team <team@quadkit.dev>
-Maintainer-email: Quadkit Framework Team <team@quadkit.dev>
+Author-email: Quadkit Framework Team <hello@oridecon.dev>
+Maintainer-email: Quadkit Framework Team <hello@oridecon.dev>
 License: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
@@ -75,7 +75,7 @@ SQL database abstractions for Quadkit Framework — Postgres, MySQL, SQLite with
 ---
 
 
-> Full documentation: [docs.quadkit.dev](https://docs.quadkit.dev)
+> Full documentation: [oridecon.dev/quadkit](https://oridecon.dev/quadkit)
 ## Install
 
 ```bash

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/README.md

@@ -11,7 +11,7 @@ SQL database abstractions for Quadkit Framework — Postgres, MySQL, SQLite with
 ---
 
 
-> Full documentation: [docs.quadkit.dev](https://docs.quadkit.dev)
+> Full documentation: [oridecon.dev/quadkit](https://oridecon.dev/quadkit)
 ## Install
 
 ```bash

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-sql"
-version = "0.0.44"
+version = "0.0.46"
 description = "SQL database abstractions for Quadkit Framework — Postgres, MySQL, SQLite with migrations, repositories, and query building"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -49,10 +49,10 @@ dependencies = [
     "anyio>=4.0.0",
 ]
 authors = [
-    { name = "Quadkit Framework Team", email = "team@quadkit.dev" },
+    { name = "Quadkit Framework Team", email = "hello@oridecon.dev" },
 ]
 maintainers = [
-    { name = "Quadkit Framework Team", email = "team@quadkit.dev" },
+    { name = "Quadkit Framework Team", email = "hello@oridecon.dev" },
 ]
 
 [project.license]
@@ -93,9 +93,9 @@ all = [
 ]
 
 [project.urls]
-Homepage = "https://dbtinoy-.github.io/quadkit"
+Homepage = "https://oridecon.dev"
 Repository = "https://github.com/dbtinoy-/quadkit"
-Documentation = "https://dbtinoy-.github.io/quadkit"
+Documentation = "https://oridecon.dev/quadkit/"
 Issues = "https://github.com/dbtinoy-/quadkit/issues"
 Changelog = "https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md"
 

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/__init__.py

@@ -157,6 +157,7 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "DatabaseConfig": ("quadkit.sql.config", "DatabaseConfig"),
     "DatabaseError": ("quadkit.sql.exceptions", "DatabaseError"),
     "DatabaseModule": ("quadkit.sql.module", "DatabaseModule"),
+    "SessionFactory": ("quadkit.sql.orm.session", "SessionFactory"),
     "DatabaseProvider": ("quadkit.sql.di.provider", "DatabaseProvider"),
     "DatabaseMonitor": ("quadkit.sql.monitoring.database_monitor", "DatabaseMonitor"),
     "DatabaseService": ("quadkit.sql.providers", "DatabaseService"),
@@ -322,6 +323,7 @@ __all__ = [
     "SQLiteProvider",
     "Schema",
     "ScopeColumn",
+    "SessionFactory",
     "SimpleConnectionPool",
     "SimpleMigrationManager",
     "SimpleTransactionManager",

quadkit_sql-0.0.46/src/quadkit/sql/admin/registration.py

@@ -0,0 +1,84 @@
+"""Public registration of the SQL admin widget handlers.
+
+``SqlAdminContributor`` resolves its three widget handlers from the DI
+container in ``on_admin_boot``. The contributor itself is discovered through
+the ``the optional provider module`` entry-point group, so it mounts in *any*
+application that installs ``quadkit-sql`` — including applications that own
+their database provider instead of using
+:class:`~quadkit.sql.di.provider.DatabaseProvider`. Those applications still
+have to register the handlers, or the contributor boots into a
+``UnresolvableDependencyError`` and the Database widgets render nothing.
+
+This module owns that registration so it lives in exactly one place: the
+framework provider delegates to it, and applications with their own provider
+call it directly.
+
+Example:
+    ```python
+    from quadkit.sql.admin.registration import register_admin_widget_handlers
+
+    register_admin_widget_handlers(container, db=my_database_provider)
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from quadkit.logging import get_logger
+
+if TYPE_CHECKING:  # pragma: no cover — typing only
+    from quadkit.contracts.core.di import ContainerRegistrarProtocol
+
+logger = get_logger(__name__)
+
+
+def register_admin_widget_handlers(
+    container: ContainerRegistrarProtocol,
+    *,
+    db: Any = None,
+    migration_manager: Any = None,
+    migration_runner: Any = None,
+) -> None:
+    """Register the SQL admin widget handlers as container singletons.
+
+    Args:
+        container: DI registrar to bind the handlers into.
+        db: Database provider exposing ``get_primary_pool()``. ``None`` is
+            accepted — the pool widgets then report ``Unavailable`` instead of
+            failing, which is the honest answer when no pool is wired.
+        migration_manager: Migration manager behind the migration-status
+            widget. ``None`` renders the widget as unavailable.
+        migration_runner: Optional runner used to compute pending migrations.
+    """
+    from quadkit.sql.admin.handlers.migration_status import (
+        MigrationStatusWidgetHandler,
+    )
+    from quadkit.sql.admin.handlers.pool_utilization import (
+        PoolUtilizationWidgetHandler,
+    )
+    from quadkit.sql.admin.handlers.query_stats import QueryStatsWidgetHandler
+
+    container.singleton(
+        PoolUtilizationWidgetHandler,
+        lambda: PoolUtilizationWidgetHandler(db=db),
+    )
+    container.singleton(
+        QueryStatsWidgetHandler,
+        lambda: QueryStatsWidgetHandler(db=db),
+    )
+    container.singleton(
+        MigrationStatusWidgetHandler,
+        lambda: MigrationStatusWidgetHandler(
+            migration_manager=migration_manager,
+            migration_runner=migration_runner,
+        ),
+    )
+    logger.info(
+        "sql.admin_widgets_registered",
+        pool_widgets=db is not None,
+        migration_widget=migration_manager is not None,
+    )
+
+
+__all__ = ["register_admin_widget_handlers"]

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/generators/database_repository.py

@@ -70,6 +70,18 @@ class DatabaseRepositoryGenerator(GeneratorBase):
             ),
             key_field=str(options.get("key_field") or "id"),
             needs_datetime=any(f["import_datetime"] for f in fields),
+            # The not-found error the repository returns. The built-in
+            # default is the contracts family member, so a standalone CLI
+            # render behaves exactly as before; an app whose exceptions live
+            # in its own module (the generated modular layout) passes the
+            # class name and import root — the class is the one named type
+            # for the outcome, and R6's one lineage keeps the Result
+            # bridge's status mapping uniform.
+            not_found_error=str(options.get("not_found_error") or "NotFoundError"),
+            exceptions_module=str(
+                options.get("exceptions_module") or "quadkit.contracts.exceptions"
+            ),
+            exceptions_first_party=bool(options.get("exceptions_first_party") or False),
         )
 
         self.stage(file_path, content)

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/generators/service.py

@@ -64,6 +64,34 @@ class ServiceGenerator(GeneratorBase):
                 for field in fields
             ],
         }
+        context.update(
+            {
+                # One named error type per outcome, declared once: the
+                # class, its import root, and the service's declared union.
+                # The standalone-CLI defaults keep the contracts family;
+                # a modular app passes its per-context exceptions module so
+                # the lineage runs one entity-named type end to end.
+                "not_found_error": str(
+                    options.get("not_found_error") or "NotFoundError"
+                ),
+                "exceptions_module": str(
+                    options.get("exceptions_module") or "quadkit.contracts.exceptions"
+                ),
+                "service_error_union": str(
+                    options.get("service_error_union")
+                    or options.get("not_found_error")
+                    or "NotFoundError"
+                ),
+                # Isort groups change with first-party membership: the
+                # framework's contracts module sorts inside the third-party
+                # block; a generated app's own exceptions module ships
+                # ``[tool.ruff] src = ["src"]``, so it is first-party and
+                # earns the trailing group. One template, one profile each.
+                "exceptions_first_party": bool(
+                    options.get("exceptions_first_party") or False
+                ),
+            }
+        )
         content = self.render_template("service.py.jinja2", context)
         file_path = self.output_dir / f"{snake_name}_service.py"
         self.stage(file_path, content)

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/templates/database_repository.py.jinja2

@@ -1,4 +1,8 @@
-"""{{ entity_name }} repository."""
+"""Convention followed: **Repository pattern** — this module owns the
+row<->entity mapping only; every read/write goes through
+``GenericRepository`` plus the injected provider.
+
+{{ entity_name }} repository."""
 
 from __future__ import annotations
 
@@ -8,16 +12,19 @@ import uuid as _uuid
 {% endif %}
 from quadkit import clock
 from quadkit.contracts import DatabaseProviderProtocol
-
+{% if not exceptions_first_party %}from {{ exceptions_module }} import {{ not_found_error }}
+{% endif %}from quadkit.result import Err, Ok, Result
+from quadkit.serialization.domain import json_serialize
 from quadkit.sql.repositories.generic_repository import GenericRepository
+{% if exceptions_first_party %}
+
+from {{ exceptions_module }} import {{ not_found_error }}
+{% endif %}
 
 
 class {{ entity_name }}Entity:
     """{{ entity_name }} row entity (plain attrs; swap for a model later)."""
-
-{% for field in fields %}
-    {{ field.name }}: {{ field.py_type }}{% if not field.required %} | None = None{% endif %}
-
+{% for field in fields %}    {{ field.name }}: {{ field.py_type }}{% if not field.required %} | None = None{% endif %}
 {% endfor %}
     def __init__(self, **kwargs: Any) -> None:
         for key, value in kwargs.items():
@@ -27,8 +34,12 @@ class {{ entity_name }}Entity:
 class _{{ repo_name }}Inner(GenericRepository[{{ entity_name }}Entity, str]):
     """Row mapper bridge over the generic SQL repository."""
 
-    def _entity_to_dict(self, entity: {{ entity_name }}Entity) -> dict[str, Any]:
-        return dict(vars(entity))
+    def _serialize_entity(self, entity: {{ entity_name }}Entity) -> dict[str, Any]:
+        """Row dict via the framework serializer (datetime/UUID/enum-safe)."""
+        serialized = json_serialize(entity)
+        if isinstance(serialized, dict):
+            return serialized
+        return {"value": serialized}
 
     def _row_to_entity(self, row: dict[str, Any]) -> {{ entity_name }}Entity:
         return self.entity_class(**dict(row))
@@ -70,17 +81,28 @@ class {{ repo_name }}Repository:
             )
         return found
 
-    async def get(self, key: str) -> dict[str, Any] | None:
+    async def get(self, key: str) -> Result[dict[str, Any], {{ not_found_error }}]:
+        """A row that is not there is an expected outcome: absence travels
+        as ``Err({{ not_found_error }})`` — a value — never as ``None`` (R6)."""
         entity = await self._inner.find_by_id(key)
         if entity is None:
-            return None
-        return self._inner._entity_to_dict(entity)
+            return Err(
+                {{ not_found_error }}(f"{{ entity_name }} not found with id: {key}")
+            )
+        return Ok(self._inner._serialize_entity(entity))
 
     async def list(self, limit: int = 50) -> list[dict[str, Any]]:
         entities = await self._inner.find(limit=limit)
-        return [self._inner._entity_to_dict(e) for e in entities]
-
-    async def update(self, key: str, data: dict[str, Any]) -> dict[str, Any] | None:
+        return [self._inner._serialize_entity(e) for e in entities]
+
+    async def update(
+        self, key: str, data: dict[str, Any]
+    ) -> Result[dict[str, Any], {{ not_found_error }}]:
+        existing = await self._inner.find_by_id(key)
+        if existing is None:
+            return Err(
+                {{ not_found_error }}(f"{{ entity_name }} not found with id: {key}")
+            )
         async with self._provider.transaction():
             row = {
                 **data,
@@ -90,7 +112,17 @@ class {{ repo_name }}Repository:
             await self._provider.execute_update(
                 "{{ table_name }}", row, '"{{ key_field }}" = ?', [key]
             )
-            return await self.get(key)
-
-    async def delete(self, key: str) -> bool:
-        return await self._inner.delete_by_id(key)
+        return await self.get(key)
+
+    async def delete(self, key: str) -> Result[bool, {{ not_found_error }}]:
+        """Deleting a row that is not there is an expected outcome, so it
+        travels as ``Err({{ not_found_error }})`` — one named error type for the
+        outcome, defined once, instead of a truthiness every caller must
+        re-read (R6). Harder faults (a dead connection) stay on the throw
+        path."""
+        removed = await self._inner.delete_by_id(key)
+        if not removed:
+            return Err(
+                {{ not_found_error }}(f"{{ entity_name }} not found with id: {key}")
+            )
+        return Ok(True)

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/templates/entity_migration.py.jinja2

@@ -3,6 +3,9 @@
 Revision ID: {{ rev_id }}
 Revises: {{ prev_rev if prev_rev else "" }}
 Create Date: auto
+
+Every table carries ``id`` + ``created_at``/``updated_at``; the entity
+columns follow. Downgrade drops the table.
 """
 
 from __future__ import annotations

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/templates/entity_model.py.jinja2

@@ -1,4 +1,8 @@
-"""{{ entity_name }} entity model.
+"""Convention followed: **Domain model pattern** — one shape per
+entity: the model carries the stored fields, the Create/Update DTOs
+carry the write shapes; repository and controller share them.
+
+{{ entity_name }} entity model.
 {% if extra_dependencies %}
 
 Requires: {{ extra_dependencies | join(', ') }} — install it alongside pydantic

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/templates/health_check.py.jinja2

@@ -1,4 +1,9 @@
-"""Health Check for {{ name }}."""
+"""Health check for {{ snake_name }}.
+
+Reports HEALTHY/UNHEALTHY through the result object — failures are
+captured, never raised, so one sick component cannot take down the
+readiness endpoint.
+"""
 
 from quadkit.contracts.core import HealthCheckResult, HealthStatus
 from quadkit.monitor.health import HealthCheck

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/cli/templates/seeder.py.jinja2

@@ -1,4 +1,9 @@
-"""Database seeder for {{ model_name }}."""
+"""Database seeder for {{ model_name }}.
+
+Starter rows live in ``SEED_DATA``; ``run()`` inserts them once and
+skips when the table is already populated. Edit ``SEED_DATA`` to
+change what a fresh database contains.
+"""
 
 from __future__ import annotations
 

quadkit_sql-0.0.46/src/quadkit/sql/cli/templates/service.py.jinja2

@@ -0,0 +1,159 @@
+"""Convention followed: **Service pattern** — domain logic behind a
+small class the provider binds; controllers call the service, never
+the provider. Writes commit through the unit of work, reads go
+straight through. Handlers that can fail on *expected* domain
+outcomes (a row that is not there) return ``Result[T, E]``
+(Convention: **Result + ProblemDetail**) instead of ``None``: the
+web layer's Result bridge renders ``Err(NotFoundError)`` as a
+404 RFC-9457 ``ProblemDetail``. Infra faults (a dead connection) stay
+on the throw path — they are not domain outcomes.
+
+Application service for {{ resource_name }} backed by the SQL unit of work.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from quadkit.contracts import DatabaseProviderProtocol
+{% if not exceptions_first_party %}from {{ exceptions_module }} import {{ not_found_error }}{% if service_error_union != not_found_error %}, {{ service_error_union }}{% endif %}
+{% endif %}from quadkit.logging import get_logger
+from quadkit.result import Err, Ok, Result
+from quadkit.sql.unit_of_work import SimpleUnitOfWork
+{% if exceptions_first_party %}
+
+from {{ exceptions_module }} import {{ not_found_error }}{% if service_error_union != not_found_error %}, {{ service_error_union }}{% endif %}
+{% endif %}
+logger = get_logger(__name__)
+
+
+class {{ entity_class_name }}:
+    """Row entity for the ``{{ table_name }}`` table."""
+
+    __table_name__ = "{{ table_name }}"
+
+    def __init__(self, **data: Any) -> None:
+        """Populate row attributes from *data*."""
+        for key, value in data.items():
+            setattr(self, key, value)
+
+
+class {{ class_name }}Service:
+    """Service for {{ resource_name }}.
+
+    Write operations use :class:`~quadkit.sql.SimpleUnitOfWork` so entity
+    changes and domain events commit atomically.  Single-statement reads go
+    straight through the injected :class:`~quadkit.contracts.DatabaseProviderProtocol`.
+    """
+
+    def __init__(self, provider: DatabaseProviderProtocol) -> None:
+        """Initialize the service.
+
+        Args:
+            provider: Database provider (typically resolved from DI after
+                registering :class:`~quadkit.sql.di.provider.DatabaseProvider`).
+        """
+        self._provider = provider
+
+    async def create(
+        self, data: dict[str, Any]
+    ) -> Result[dict[str, Any], {{ service_error_union }}]:
+        """Persist a new ``{{ table_name }}`` row.
+
+        Args:
+            data: Row values{% if fields %} (keys: {% for field in fields %}{{ field.name }}{% if not loop.last %}, {% endif %}{% endfor %}){% endif %}.
+
+        Returns:
+            ``Ok(row)`` — the persisted row data. Writes that cannot
+            legitimately fail still answer with the service's union so every
+            consumer chains: ``get(...).map(...)`` and
+            ``create(...).and_then(...)`` share one shape.
+        """
+        async with SimpleUnitOfWork(self._provider) as uow:
+            uow.register_new({{ entity_class_name }}(**data))
+            await uow.commit()
+        logger.info("{{ snake_name }}_created", table="{{ table_name }}")
+        return Ok(data)
+
+    async def get(
+        self, entity_id: Any
+    ) -> Result[dict[str, Any], {{ service_error_union }}]:
+        """Fetch a ``{{ table_name }}`` row by primary key.
+
+        Args:
+            entity_id: Primary key value.
+
+        Returns:
+            ``Ok(row)`` when the row exists, ``Err(...)`` when it
+            does not — absence is an expected outcome, so it travels as a
+            value, never as ``None``.
+        """
+        result = await self._provider.execute_query(
+            "SELECT * FROM {{ table_name }} WHERE id = ?",
+            params=[entity_id],
+        )
+        if not result.rows:
+            return Err(
+                {{ not_found_error }}(f"{{ table_name }} row not found with id: {entity_id}")
+            )
+        return Ok(result.rows[0])
+
+    async def update(
+        self, entity_id: Any, data: dict[str, Any]
+    ) -> Result[dict[str, Any], {{ service_error_union }}]:
+        """Merge *data* into one ``{{ table_name }}`` row by primary key.
+
+        The row being gone is the same expected outcome as ``get`` — the
+        Err arm comes straight through — so the write happens only for a
+        row that answered ``Ok``.
+        """
+        existing = await self.get(entity_id)
+        if existing.is_err():
+            return Err(existing.unwrap_err())
+        async with SimpleUnitOfWork(self._provider) as uow:
+            uow.register_dirty({{ entity_class_name }}(id=entity_id, **data))
+            await uow.commit()
+        logger.info("{{ snake_name }}_updated", table="{{ table_name }}")
+        return Ok(data)
+
+    async def list(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> Result[list[dict[str, Any]], {{ service_error_union }}]:
+        """List ``{{ table_name }}`` rows with pagination.
+
+        Args:
+            limit: Maximum number of rows.
+            offset: Number of rows to skip.
+
+        Returns:
+            ``Ok(rows)``. An empty page is a value, and its uniform arm
+            keeps reads chainable with the outcome-bearing methods.
+        """
+        result = await self._provider.execute_query(
+            "SELECT * FROM {{ table_name }} LIMIT ? OFFSET ?",
+            params=[limit, offset],
+        )
+        return Ok(result.rows)
+
+    async def delete(
+        self, entity_id: Any
+    ) -> Result[bool, {{ service_error_union }}]:
+        """Delete a ``{{ table_name }}`` row by primary key.
+
+        The existence check travels as the ``Err`` arm: deleting a missing
+        row answers ``Err`` (the bridge renders 404), a real
+        delete answers ``Ok(True)``.
+
+        Args:
+            entity_id: Primary key value.
+        """
+        existing = await self.get(entity_id)
+        if existing.is_err():
+            return Err(existing.unwrap_err())
+        async with SimpleUnitOfWork(self._provider) as uow:
+            uow.register_deleted({{ entity_class_name }}(id=entity_id))
+            await uow.commit()
+        logger.info("{{ snake_name }}_deleted", table="{{ table_name }}")
+        return Ok(True)

{quadkit_sql-0.0.44 → quadkit_sql-0.0.46}/src/quadkit/sql/di/_registration.py

@@ -112,6 +112,25 @@ class _DatabaseRegistrationMixin:
         # Register admin widget services
         self._register_admin_widgets(container)
 
+    def _make_session_factory(self, name: str, backend: Any) -> Any:
+        """Build (once) the ORM session factory for one backend.
+
+        Memoised so repeated resolution shares the engine rather than
+        quietly opening another pool — which is the very problem this
+        feature exists to remove.
+        """
+        from quadkit.sql.orm.session import SessionFactory
+
+        existing = self._session_factories.get(name)
+        if existing is not None:
+            return existing
+        factory = SessionFactory(
+            backend.url.get_secret_value(),
+            echo=bool(getattr(backend, "echo", False)),
+        )
+        self._session_factories[name] = factory
+        return factory
+
     async def _register_single_backend(
         self,
         container: ContainerRegistrarProtocol,
@@ -125,6 +144,7 @@ class _DatabaseRegistrationMixin:
             QueryLoggerProtocol,
             UnitOfWorkProtocol,
         )
+        from quadkit.sql.orm.session import SessionFactory
 
         self._db_provider = self._db_provider or DatabaseService(
             config, clock=self._clock, id_generator=self._id_generator
@@ -132,6 +152,21 @@ class _DatabaseRegistrationMixin:
         container.singleton(DatabaseService, self._db_provider)
         container.singleton(DatabaseProviderProtocol, self._db_provider)
 
+        # ORM session factory: one engine and one pool shared with the raw
+        # providers, so an application mapping declarative models does not
+        # build a second engine against the same database
+        # (Improve-QuadKit #1).
+        #
+        # Registered as a FACTORY, not an instance: the engine is built
+        # only if something resolves it. Building eagerly would also fail
+        # for apps configured with a sync driver (`sqlite://` rather than
+        # `sqlite+aiosqlite://`), which use the raw providers happily and
+        # never ask for an ORM session.
+        container.singleton(
+            SessionFactory,
+            factory=lambda: self._make_session_factory("default", config.backend),
+        )
+
         # Protocol bindings for optional collaborators
         container.singleton(
             ConnectionPoolProtocol,
@@ -212,12 +247,15 @@ class _DatabaseRegistrationMixin:
             QueryLoggerProtocol,
             UnitOfWorkProtocol,
         )
+        from quadkit.sql.orm.session import SessionFactory
 
         backends = config.backends
         primary_entry = next((b for b in backends if b.primary), backends[0])
 
         self._db_services = []
+        self._session_factories: dict[str, Any] = {}
         primary_svc: Any = None
+        primary_factory: Any = None
 
         for entry in backends:
             db_cfg = DatabaseConfig.from_named(entry, base=config)
@@ -263,13 +301,31 @@ class _DatabaseRegistrationMixin:
                     container, db_svc, entry.migration_dir, name=entry.name
                 )
 
+            # ORM session factory: one engine and one pool per backend, so
+            # an application mapping declarative models does not build a
+            # second engine against the same database (Improve-QuadKit #1).
+            # Engine construction is lazy — no connection is opened here.
+            container.singleton(
+                SessionFactory,
+                name=entry.name,
+                factory=lambda e=entry: self._make_session_factory(e.name, e.backend),
+            )
+
             if entry.name == primary_entry.name:
                 primary_svc = db_svc
+                primary_factory = entry
 
         # Primary backend also gets the unnamed bindings (backward compat)
         self._db_provider = primary_svc
         container.singleton(DatabaseProviderProtocol, instance=primary_svc)
         container.singleton(DatabaseService, instance=primary_svc)
+        if primary_factory is not None:
+            container.singleton(
+                SessionFactory,
+                factory=lambda e=primary_factory: self._make_session_factory(
+                    e.name, e.backend
+                ),
+            )
 
         container.scoped(UnitOfWorkProtocol, primary_svc.get_unit_of_work)  # type: ignore[type-abstract]