Version 5.0.0-beta1

chore: rework DB module (#324 )
⬆ Bump starlette from 1.0.1 to 1.3.1 (#315 )
2026-08-04 23:54:09 +00:00 · 2026-06-25 15:15:49 -04:00 · 2026-06-25 21:11:50 +02:00 · 2026-06-20 15:27:11 +02:00 · 2026-06-09 12:48:01 -04:00 · 2026-06-09 18:46:09 +02:00
25 changed files with 1996 additions and 1026 deletions
@@ -167,7 +167,7 @@ user = await UserCrud.update(session, UserUpdate(credits=10), [User.id == user_i
 ```

 !!! warning
-    `with_for_update` requires an open transaction. Wrap your call in `async with session.begin()` or use the `get_transaction` helper if you are not already inside one.
+    `with_for_update` requires an open transaction. Wrap your call in `async with session.begin()` or use the `transaction` helper if you are not already inside one.

 !!! note
    `NOWAIT` raises `sqlalchemy.exc.OperationalError` immediately if the row is locked rather than waiting.
@@ -7,96 +7,137 @@ SQLAlchemy async session management with transactions, table locking, advisory l

 ## Overview

-The `db` module provides helpers to create FastAPI dependencies and context managers for `AsyncSession`, along with utilities for nested transactions, table locks, advisory locks, and polling for row changes.
+The `db` module is built around one object, [`Database`](../reference/db.md#fastapi_toolsets.db.Database), which owns the engine and sessionmaker and exposes the FastAPI dependency, a commit-before-response middleware, session/transaction context managers, and table locking. Free helpers cover savepoint-aware transactions, advisory locks, many-to-many association tables, and row-change polling.

-## Session dependency
+## Setup

-Use [`create_db_dependency`](../reference/db.md#fastapi_toolsets.db.create_db_dependency) to create a FastAPI dependency that yields a session and auto-commits on success:
+Create one `Database` for your app. Provide a **URL** (the facade builds and disposes the engine) or pass an existing **`engine=`** you own (e.g. for Alembic or `event.listen`). The session factory is built internally with `expire_on_commit=False`.

 ```python
-from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
-from fastapi_toolsets.db import create_db_dependency
+from fastapi import Depends, FastAPI
+from sqlalchemy.ext.asyncio import AsyncSession

-engine = create_async_engine(url="postgresql+asyncpg://...", future=True)
-session_maker = async_sessionmaker(bind=engine, expire_on_commit=False)
+from fastapi_toolsets.db import Database

-get_db = create_db_dependency(session_maker=session_maker)
+db = Database("postgresql+asyncpg://postgres:postgres@localhost/app")

-@router.get("/users")
-async def list_users(session: AsyncSession = Depends(get_db)):
+app = FastAPI()
+db.install(app)  # commit middleware + engine disposal on shutdown
+
+@app.get("/users")
+async def list_users(session: AsyncSession = Depends(db)):
    ...
 ```

-## Session context manager
+The `Database` instance **is** the dependency: use it directly as `Depends(db)`. The whole request runs as a single transaction (CRUD writes use savepoints under it).

-Use [`create_db_context`](../reference/db.md#fastapi_toolsets.db.create_db_context) for sessions outside request handlers (e.g. background tasks, CLI commands):
+## Committing before the response
+
+[`db.install(app)`](../reference/db.md#fastapi_toolsets.db.Database) adds a middleware that commits the request's session when the response starts, after the endpoint returns and before the body is sent. With the middleware installed, the dependency does not commit again.
+
+The request is committed as a single transaction:
+
+- **Read-after-write**: a follow-up request sees the write.
+- **Atomicity**: multi-write endpoints roll back as a unit on failure.
+- **Errors roll back**: on a raised exception the session rolls back and nothing is committed.
+
+Without `install`, the session commits in the dependency teardown, which runs after the response has been sent.
+
+!!! warning "Streaming / SSE endpoints"
+    For a `StreamingResponse` / `EventSourceResponse`, the commit fires at the **start** of the stream. A stream that **writes** must open a short-lived session per write with [`db.session()`](#session-context-manager); the start-time commit will not flush writes made later during the stream.
+
+## Lifespan
+
+`db.install(app)` disposes the engine on shutdown, composing around your own lifespan:

 ```python
-from fastapi_toolsets.db import create_db_context
+from contextlib import asynccontextmanager

-db_context = create_db_context(session_maker=session_maker)
+@asynccontextmanager
+async def lifespan(app):
+    await warm_cache()   # your startup
+    yield
+    await flush_metrics()  # your shutdown

+app = FastAPI(lifespan=lifespan)
+db.install(app)  # your shutdown runs first, then the engine is disposed
+```
+
+If you have no lifespan of your own, [`db.lifespan`](../reference/db.md#fastapi_toolsets.db.Database) works standalone as `FastAPI(lifespan=db.lifespan)`. Engine disposal is idempotent and is a no-op when you passed your own `engine=`.
+
+## Session context manager
+
+Use [`db.session()`](../reference/db.md#fastapi_toolsets.db.Database) for sessions outside request handlers (e.g. background tasks, CLI commands). It commits on clean exit and rolls back on exception:
+
+```python
 async def seed():
-    async with db_context() as session:
+    async with db.session() as session:
        ...
 ```

-## Nested transactions
+## Transactions

-[`get_transaction`](../reference/db.md#fastapi_toolsets.db.get_transaction) handles savepoints automatically, allowing safe nesting:
+[`transaction`](../reference/db.md#fastapi_toolsets.db.transaction) opens a transaction on a session, using a savepoint when one is already open so it nests safely:

 ```python
-from fastapi_toolsets.db import get_transaction
+from fastapi_toolsets.db import transaction

-async def create_user_with_role(session=session):
-    async with get_transaction(session=session):
+async def create_user_with_role(session):
+    async with transaction(session):
        ...
-        async with get_transaction(session=session):  # uses savepoint
+        async with transaction(session):  # uses a savepoint
            ...
 ```

+When you have a `Database`, [`db.begin()`](../reference/db.md#fastapi_toolsets.db.Database) opens a session already inside a transaction:
+
+```python
+async with db.begin() as session:
+    session.add(User(name="ada"))  # commits on exit, rolls back on exception
+```
+
 ## Table locking

-[`lock_tables`](../reference/db.md#fastapi_toolsets.db.lock_tables) acquires PostgreSQL table-level locks before executing critical sections. It opens a **dedicated session** internally and yields it to the caller, so the lock is guaranteed to be released when the context exits:
+[`db.lock_tables`](../reference/db.md#fastapi_toolsets.db.Database) acquires PostgreSQL table-level locks for a critical section. It opens a dedicated session internally and releases the lock when the context exits:

 ```python
-from fastapi_toolsets.db import lock_tables, LockMode
+from fastapi_toolsets.db import LockMode

-async with lock_tables(session_maker=session_maker, tables=[User], mode=LockMode.EXCLUSIVE) as session:
+async with db.lock_tables([User], mode=LockMode.EXCLUSIVE) as session:
    # No other transaction can modify User until this block exits
    ...
 ```

 Available lock modes are defined in [`LockMode`](../reference/db.md#fastapi_toolsets.db.LockMode): `ACCESS_SHARE`, `ROW_SHARE`, `ROW_EXCLUSIVE`, `SHARE_UPDATE_EXCLUSIVE`, `SHARE`, `SHARE_ROW_EXCLUSIVE`, `EXCLUSIVE`, `ACCESS_EXCLUSIVE`.

-Pass `timeout` to limit how long the lock waits before giving up. On timeout, a [`LockTimeoutError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.LockTimeoutError) is raised instead of a raw database error:
+Pass `timeout` to limit how long the lock waits. On timeout, a [`LockTimeoutError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.LockTimeoutError) is raised instead of a raw database error:

 ```python
-async with lock_tables(session_maker, [Order], timeout="2s") as session:
+async with db.lock_tables([Order], timeout="2s") as session:
    ...
 ```

 ## Advisory locking

-[`advisory_lock`](../reference/db.md#fastapi_toolsets.db.advisory_lock) acquires a PostgreSQL session-level advisory lock. The lock is released explicitly when the context exits, regardless of whether the transaction has committed.
+[`advisory_lock`](../reference/db.md#fastapi_toolsets.db.advisory_lock) acquires a PostgreSQL session-level advisory lock on a session you provide. The lock is released when the context exits:

 ```python
 from fastapi_toolsets.db import advisory_lock

-# Blocking exclusive lock — waits until the lock is free
+# Blocking exclusive lock: waits until the lock is free
 async with advisory_lock(session=session, key=42):
    ...

-# Non-blocking — yields False immediately if already held
+# Non-blocking: yields False immediately if already held
 async with advisory_lock(session=session, key=42, nowait=True) as acquired:
    if not acquired:
        raise HTTPException(409, "Resource is locked")

-# Blocking with a timeout — raises LockTimeoutError if not acquired in time
+# Blocking with a timeout: raises LockTimeoutError if not acquired in time
 async with advisory_lock(session=session, key=42, timeout="5s"):
    ...

-# Shared — multiple readers allowed simultaneously, blocks exclusive writers
+# Shared lock: multiple readers allowed simultaneously, blocks exclusive writers
 async with advisory_lock(session=session, key=42, shared=True):
    ...

@@ -106,11 +147,11 @@ async with advisory_lock(session=session, key=(1, user_id)):
 ```

 !!! note
-    Advisory locks use PostgreSQL session-level functions (`pg_advisory_lock` / `pg_advisory_unlock`). The lock is tied to the database connection, not the SQLAlchemy transaction — it is released when the context exits, even if the surrounding transaction is still open.
+    Advisory locks use PostgreSQL session-level functions (`pg_advisory_lock` / `pg_advisory_unlock`). The lock is tied to the database connection, not the SQLAlchemy transaction, so it is released when the context exits even if the surrounding transaction is still open.

 ## Row-change polling

-[`wait_for_row_change`](../reference/db.md#fastapi_toolsets.db.wait_for_row_change) polls a row until a specific column changes value, useful for waiting on async side effects:
+[`wait_for_row_change`](../reference/db.md#fastapi_toolsets.db.wait_for_row_change) polls a row until a specific column changes value:

 ```python
 from fastapi_toolsets.db import wait_for_row_change
@@ -120,7 +161,7 @@ await wait_for_row_change(
    session=session,
    model=Order,
    pk_value=order_id,
-    columns=[Order.status],
+    columns=["status"],
    interval=1.0,
    timeout=30.0,
 )
@@ -128,28 +169,24 @@ await wait_for_row_change(

 ## Creating a database

-!!! info "Added in `v2.1`"
-
-[`create_database`](../reference/db.md#fastapi_toolsets.db.create_database) creates a database at a given URL. It connects to *server_url* and issues a `CREATE DATABASE` statement:
+[`create_database`](../reference/db.md#fastapi_toolsets.db.testing.create_database) (in `fastapi_toolsets.db.testing`) connects to *server_url* and issues a `CREATE DATABASE` statement:

 ```python
-from fastapi_toolsets.db import create_database
+from fastapi_toolsets.db.testing import create_database

 SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"

 await create_database(db_name="myapp_test", server_url=SERVER_URL)
 ```

-For test isolation with automatic cleanup, use [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) from the `pytest` module instead — it handles drop-before, create, and drop-after automatically.
+For test isolation with automatic cleanup, use [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) from the `pytest` module, which handles drop-before, create, and drop-after.

 ## Cleaning up tables

-!!! info "Added in `v2.1`"
-
-[`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.cleanup_tables) truncates all tables:
+[`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.testing.cleanup_tables) (in `fastapi_toolsets.db.testing`) truncates all tables:

 ```python
-from fastapi_toolsets.db import cleanup_tables
+from fastapi_toolsets.db.testing import cleanup_tables

@pytest.fixture(autouse=True)
 async def clean(db_session):
@@ -159,50 +196,50 @@ async def clean(db_session):

 ## Many-to-Many helpers

-SQLAlchemy's ORM collection API triggers lazy-loads when you append to a relationship inside a savepoint (e.g. inside `lock_tables` or a nested `get_transaction`). The three `m2m_*` helpers bypass the ORM collection entirely and issue direct SQL against the association table.
+The three `m2m_*` helpers modify a many-to-many association table with direct SQL, without loading the ORM collection.

-### `m2m_add` — insert associations
+### `m2m_add`: insert associations

-[`m2m_add`](../reference/db.md#fastapi_toolsets.db.m2m_add) inserts one or more rows into a secondary table without touching the ORM collection:
+[`m2m_add`](../reference/db.md#fastapi_toolsets.db.m2m_add) inserts one or more rows into a secondary table:

 ```python
-from fastapi_toolsets.db import lock_tables, m2m_add
+from fastapi_toolsets.db import m2m_add

-async with lock_tables(session_maker, [Tag]) as session:
+async with db.lock_tables([Tag]) as session:
    tag = await TagCrud.create(session, TagCreate(name="python"))
    await m2m_add(session, post, Post.tags, tag)
 ```

-Pass `ignore_conflicts=True` to silently skip associations that already exist:
+Pass `ignore_conflicts=True` to skip associations that already exist:

 ```python
 await m2m_add(session, post, Post.tags, tag, ignore_conflicts=True)
 ```

-### `m2m_remove` — delete associations
+### `m2m_remove`: delete associations

 [`m2m_remove`](../reference/db.md#fastapi_toolsets.db.m2m_remove) deletes specific association rows. Removing a non-existent association is a no-op:

 ```python
-from fastapi_toolsets.db import get_transaction, m2m_remove
+from fastapi_toolsets.db import m2m_remove, transaction

-async with get_transaction(session):
+async with transaction(session):
    await m2m_remove(session, post, Post.tags, tag1, tag2)
 ```

-### `m2m_set` — replace the full set
+### `m2m_set`: replace the full set

-[`m2m_set`](../reference/db.md#fastapi_toolsets.db.m2m_set) atomically replaces all associations: it deletes every existing row for the owner instance then inserts the new set. Passing no related instances clears the association entirely:
+[`m2m_set`](../reference/db.md#fastapi_toolsets.db.m2m_set) replaces all associations: it deletes every existing row for the owner instance then inserts the new set. Passing no related instances clears the association:

 ```python
-from fastapi_toolsets.db import get_transaction, m2m_set
+from fastapi_toolsets.db import m2m_set, transaction

 # Replace all tags
-async with get_transaction(session):
+async with transaction(session):
    await m2m_set(session, post, Post.tags, tag_a, tag_b)

 # Clear all tags
-async with get_transaction(session):
+async with transaction(session):
    await m2m_set(session, post, Post.tags)
 ```

@@ -134,7 +134,7 @@ SessionLocal = async_sessionmaker(engine, expire_on_commit=False, class_=EventSe
 ```

 !!! info "Callbacks fire on `session.commit()` only — not on savepoints."
-    Savepoints created by [`get_transaction`](db.md) or `begin_nested()` do **not**
+    Savepoints created by [`transaction`](db.md) or `begin_nested()` do **not**
    trigger callbacks. All events accumulated across flushes are dispatched once
    when the outermost `commit()` is called.

@@ -1,6 +1,6 @@
 # Pytest

-Testing helpers for FastAPI applications with async client, database sessions, and parallel worker support.
+Testing helpers for FastAPI applications: async HTTP client, database sessions, and parallel worker support.

 ## Installation

@@ -14,13 +14,9 @@ Testing helpers for FastAPI applications with async client, database sessions, a
    pip install "fastapi-toolsets[pytest]"
    ```

-## Overview
+## Async client

-The `pytest` module provides utilities for setting up async test clients, managing test database sessions, and supporting parallel test execution with `pytest-xdist`.
-
-## Creating an async client
-
-Use [`create_async_client`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_async_client) to get an `httpx.AsyncClient` configured for your FastAPI app:
+Use [`create_async_client`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_async_client) to get an `httpx.AsyncClient` bound to your FastAPI app:

 ```python
 from fastapi_toolsets.pytest import create_async_client
@@ -38,9 +34,20 @@ async def http_client(db_session):
        yield c
 ```

-## Database sessions in tests
+Any extra keyword arguments are forwarded to `httpx.AsyncClient`, so you can set default headers, authentication, timeouts, and more:

-Use [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to create an isolated `AsyncSession` for a test, combined with [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) to set up a per-worker database:
+```python
+async with create_async_client(
+    app=app,
+    headers={"X-Api-Key": "secret"},
+    timeout=10,
+) as c:
+    ...
+```
+
+## Database sessions
+
+Use [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) + [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to get a fully isolated `AsyncSession` for each test:

 ```python
 from fastapi_toolsets.pytest import create_worker_database, create_db_session
@@ -61,28 +68,49 @@ async def db_session(worker_db_url):
        yield session
 ```

+`create_worker_database` connects without specifying a database (asyncpg falls back to the username), so the target test database does not need to exist beforehand.
+
 !!! info
-    In this example, the database is reset between each test using the argument `cleanup=True`.
+    `cleanup=True` truncates all tables between tests via `TRUNCATE … RESTART IDENTITY CASCADE`, which is faster than dropping and recreating tables.
+
+### Engine and session options
+
+Pass `engine_kwargs` or `session_kwargs` to forward options to the underlying SQLAlchemy primitives:
+
+```python
+async with create_db_session(
+    database_url=worker_db_url,
+    base=Base,
+    engine_kwargs={"pool_size": 5, "connect_args": {"timeout": 10}},
+    session_kwargs={"autoflush": False},
+) as session:
+    ...
+```
+
+## Parallel testing with pytest-xdist
+
+The fixtures above work with `pytest-xdist` out of the box. Each worker gets its own database named after the worker (e.g. `gw0`, `gw1`). Pass `prefix` to namespace the database (e.g. `prefix="myapp"` → `myapp_gw0`).

 Use [`worker_database_url`](../reference/pytest.md#fastapi_toolsets.pytest.utils.worker_database_url) to derive the per-worker URL manually if needed:

 ```python
 from fastapi_toolsets.pytest import worker_database_url

-url = worker_database_url("postgresql+asyncpg://user:pass@localhost/test_db", default_test_db="test")
-# e.g. "postgresql+asyncpg://user:pass@localhost/test_db_gw0" under xdist
+url = worker_database_url("postgresql+asyncpg://user:pass@localhost/myapp", default_test_db="test")
+# → "postgresql+asyncpg://user:pass@localhost/gw0" under xdist
+# → "postgresql+asyncpg://user:pass@localhost/test" otherwise
+
+url = worker_database_url("postgresql+asyncpg://user:pass@localhost/myapp", default_test_db="test", prefix="myapp")
+# → "postgresql+asyncpg://user:pass@localhost/myapp_gw0" under xdist
+# → "postgresql+asyncpg://user:pass@localhost/myapp_test" otherwise
 ```

-## Parallel testing with pytest-xdist
+## Manual table cleanup

-The examples above are already compatible with parallel test execution with `pytest-xdist`.
-
-## Cleaning up tables
-
-If you want to manually clean up a database you can use [`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.cleanup_tables), this will truncate all tables between tests for fast isolation:
+[`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.testing.cleanup_tables) truncates all tables in a single statement and can be called directly when you need more control:

 ```python
-from fastapi_toolsets.db import cleanup_tables
+from fastapi_toolsets.pytest import cleanup_tables

@pytest.fixture(autouse=True)
 async def clean(db_session):
@@ -1,46 +1,48 @@
 # `db`

-Here's the reference for all database session utilities, transaction helpers, and locking functions.
+Here's the reference for the `Database` facade, the transaction helper, locking
+functions, many-to-many helpers, and row-watching utilities.

 You can import them directly from `fastapi_toolsets.db`:

 ```python
 from fastapi_toolsets.db import (
+    Database,
    LockMode,
    advisory_lock,
-    cleanup_tables,
-    create_database,
-    create_db_dependency,
-    create_db_context,
-    get_transaction,
    lock_tables,
    m2m_add,
    m2m_remove,
    m2m_set,
+    transaction,
    wait_for_row_change,
 )
 ```

+## ::: fastapi_toolsets.db.Database
+
+## ::: fastapi_toolsets.db.transaction
+
 ## ::: fastapi_toolsets.db.LockMode

-## ::: fastapi_toolsets.db.create_db_dependency
-
-## ::: fastapi_toolsets.db.create_db_context
-
-## ::: fastapi_toolsets.db.get_transaction
-
 ## ::: fastapi_toolsets.db.lock_tables

 ## ::: fastapi_toolsets.db.advisory_lock

-## ::: fastapi_toolsets.db.wait_for_row_change
-
-## ::: fastapi_toolsets.db.create_database
-
-## ::: fastapi_toolsets.db.cleanup_tables
-
 ## ::: fastapi_toolsets.db.m2m_add

 ## ::: fastapi_toolsets.db.m2m_remove

 ## ::: fastapi_toolsets.db.m2m_set
+
+## ::: fastapi_toolsets.db.wait_for_row_change
+
+Admin and test helpers live in `fastapi_toolsets.db.testing`:
+
+```python
+from fastapi_toolsets.db.testing import cleanup_tables, create_database
+```
+
+## ::: fastapi_toolsets.db.testing.create_database
+
+## ::: fastapi_toolsets.db.testing.cleanup_tables
@@ -2,8 +2,10 @@ from fastapi import FastAPI

 from fastapi_toolsets.exceptions import init_exceptions_handlers

+from .db import db
 from .routes import router

 app = FastAPI()
+db.install(app=app)
 init_exceptions_handlers(app=app)
 app.include_router(router=router)
@@ -1,17 +1,14 @@
 from typing import Annotated

 from fastapi import Depends
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.ext.asyncio import AsyncSession

-from fastapi_toolsets.db import create_db_context, create_db_dependency
+from fastapi_toolsets.db import Database

 DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/postgres"

-engine = create_async_engine(url=DATABASE_URL, future=True)
-async_session_maker = async_sessionmaker(bind=engine, expire_on_commit=False)
+db = Database(url=DATABASE_URL)

-get_db = create_db_dependency(session_maker=async_session_maker)
-get_db_context = create_db_context(session_maker=async_session_maker)
+get_db = db

-
-SessionDep = Annotated[AsyncSession, Depends(get_db)]
+SessionDep = Annotated[AsyncSession, Depends(db)]
@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "4.1.1"
+version = "5.0.0b1"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -7,18 +7,21 @@ Example usage:
    from fastapi import FastAPI, Depends
    from fastapi_toolsets.exceptions import init_exceptions_handlers
    from fastapi_toolsets.crud import CrudFactory
-    from fastapi_toolsets.db import create_db_dependency
+    from fastapi_toolsets.db import Database
    from fastapi_toolsets.schemas import Response

+    db = Database("postgresql+asyncpg://postgres:postgres@localhost/app")
+
    app = FastAPI()
+    db.install(app)
    init_exceptions_handlers(app)

    UserCrud = CrudFactory(User)

    @app.get("/users/{user_id}", response_model=Response[dict])
-    async def get_user(user_id: int, session = Depends(get_db)):
+    async def get_user(user_id: int, session = Depends(db)):
        user = await UserCrud.get(session, [User.id == user_id])
        return Response(data={"user": user.username}, message="Success")
 """

-__version__ = "4.1.1"
+__version__ = "5.0.0b1"
@@ -22,7 +22,7 @@ from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
 from sqlalchemy.sql.base import ExecutableOption
 from sqlalchemy.sql.roles import WhereHavingRole

-from ..db import get_transaction
+from ..db import transaction
 from ..exceptions import InvalidOrderFieldError, NotFoundError
 from ..schemas import (
    CursorPaginatedResponse,
@@ -716,7 +716,7 @@ class AsyncCrud(Generic[ModelType]):
        Returns:
            Created model instance, or ``Response[schema]`` when ``schema`` is given.
        """
-        async with get_transaction(session):
+        async with transaction(session):
            m2m_exclude = cls._m2m_schema_fields()
            data = (
                obj.model_dump(exclude=m2m_exclude) if m2m_exclude else obj.model_dump()
@@ -1067,7 +1067,7 @@ class AsyncCrud(Generic[ModelType]):
        Raises:
            NotFoundError: If no record found
        """
-        async with get_transaction(session):
+        async with transaction(session):
            m2m_exclude = cls._m2m_schema_fields()

            # Eagerly load M2M relationships that will be updated so that
@@ -1127,7 +1127,7 @@ class AsyncCrud(Generic[ModelType]):
        Returns:
            Model instance
        """
-        async with get_transaction(session):
+        async with transaction(session):
            values = obj.model_dump(exclude_unset=True)
            q = insert(cls.model).values(**values)
            if set_:
@@ -1189,7 +1189,7 @@ class AsyncCrud(Generic[ModelType]):
        Returns:
            ``None``, or ``Response[None]`` when ``return_response=True``.
        """
-        async with get_transaction(session):
+        async with transaction(session):
            result = await session.execute(select(cls.model).where(and_(*filters)))
            objects = result.scalars().all()
            for obj in objects:
@@ -1,591 +0,0 @@
-"""Database utilities: sessions, transactions, and locks."""
-
-import asyncio
-from collections.abc import AsyncGenerator, Callable
-from contextlib import AbstractAsyncContextManager, asynccontextmanager
-from enum import Enum
-from typing import Any, TypeVar, cast
-
-import asyncpg
-from sqlalchemy import Table, delete, text, tuple_
-from sqlalchemy import exc as sa_exc
-from sqlalchemy.dialects.postgresql import insert as pg_insert
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
-from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
-from sqlalchemy.orm.relationships import RelationshipProperty
-
-from .exceptions import LockTimeoutError, NotFoundError, PoolExhaustedError
-
-
-def _is_lock_not_available(e: sa_exc.DBAPIError) -> bool:
-    return e.orig is not None and isinstance(
-        e.orig.__cause__, asyncpg.exceptions.LockNotAvailableError
-    )
-
-
-__all__ = [
-    "LockMode",
-    "advisory_lock",
-    "cleanup_tables",
-    "create_database",
-    "create_db_context",
-    "create_db_dependency",
-    "get_transaction",
-    "lock_tables",
-    "m2m_add",
-    "m2m_remove",
-    "m2m_set",
-    "wait_for_row_change",
-]
-
-
-_SessionT = TypeVar("_SessionT", bound=AsyncSession)
-
-
-def create_db_dependency(
-    session_maker: async_sessionmaker[_SessionT],
-) -> Callable[[], AsyncGenerator[_SessionT, None]]:
-    """Create a FastAPI dependency for database sessions.
-
-    Creates a dependency function that yields a session and auto-commits
-    if a transaction is active when the request completes.
-
-    Args:
-        session_maker: Async session factory from create_session_factory()
-
-    Returns:
-        An async generator function usable with FastAPI's Depends()
-
-    Example:
-        ```python
-        from fastapi import Depends
-        from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
-        from fastapi_toolsets.db import create_db_dependency
-
-        engine = create_async_engine("postgresql+asyncpg://...")
-        SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
-        get_db = create_db_dependency(SessionLocal)
-
-        @app.get("/users")
-        async def list_users(session: AsyncSession = Depends(get_db)):
-            ...
-        ```
-    """
-
-    async def get_db() -> AsyncGenerator[_SessionT, None]:
-        async with session_maker() as session:
-            try:
-                await session.connection()
-            except sa_exc.TimeoutError as e:
-                raise PoolExhaustedError() from e
-            yield session
-            if session.in_transaction():
-                await session.commit()
-
-    return get_db
-
-
-def create_db_context(
-    session_maker: async_sessionmaker[_SessionT],
-) -> Callable[[], AbstractAsyncContextManager[_SessionT]]:
-    """Create a context manager for database sessions.
-
-    Creates a context manager for use outside of FastAPI request handlers,
-    such as in background tasks, CLI commands, or tests.
-
-    Args:
-        session_maker: Async session factory from create_session_factory()
-
-    Returns:
-        An async context manager function
-
-    Example:
-        ```python
-        from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
-        from fastapi_toolsets.db import create_db_context
-
-        engine = create_async_engine("postgresql+asyncpg://...")
-        SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
-        get_db_context = create_db_context(SessionLocal)
-
-        async def background_task():
-            async with get_db_context() as session:
-                user = await UserCrud.get(session, [User.id == 1])
-                ...
-        ```
-    """
-    get_db = create_db_dependency(session_maker)
-    return asynccontextmanager(get_db)
-
-
-@asynccontextmanager
-async def get_transaction(
-    session: AsyncSession,
-) -> AsyncGenerator[AsyncSession, None]:
-    """Get a transaction context, handling nested transactions.
-
-    If already in a transaction, creates a savepoint (nested transaction).
-    Otherwise, starts a new transaction.
-
-    Args:
-        session: AsyncSession instance
-
-    Yields:
-        The session within the transaction context
-
-    Example:
-        ```python
-        async with get_transaction(session):
-            session.add(model)
-            # Auto-commits on exit, rolls back on exception
-        ```
-    """
-    if session.in_transaction():
-        async with session.begin_nested():
-            yield session
-    else:
-        async with session.begin():
-            yield session
-
-
-class LockMode(str, Enum):
-    """PostgreSQL table lock modes.
-
-    See: https://www.postgresql.org/docs/current/explicit-locking.html
-    """
-
-    ACCESS_SHARE = "ACCESS SHARE"
-    ROW_SHARE = "ROW SHARE"
-    ROW_EXCLUSIVE = "ROW EXCLUSIVE"
-    SHARE_UPDATE_EXCLUSIVE = "SHARE UPDATE EXCLUSIVE"
-    SHARE = "SHARE"
-    SHARE_ROW_EXCLUSIVE = "SHARE ROW EXCLUSIVE"
-    EXCLUSIVE = "EXCLUSIVE"
-    ACCESS_EXCLUSIVE = "ACCESS EXCLUSIVE"
-
-
-def lock_tables(
-    session_maker: async_sessionmaker[_SessionT],
-    tables: list[type[DeclarativeBase]],
-    *,
-    mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
-    timeout: str = "5s",
-) -> AbstractAsyncContextManager[_SessionT]:
-    """Lock PostgreSQL tables for the duration of a transaction.
-
-    Args:
-        session_maker: Async session factory used to create the dedicated
-            session.
-        tables: List of SQLAlchemy model classes to lock.
-        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE).
-        timeout: Lock timeout (default: "5s").
-
-    Yields:
-        The dedicated session, open within the locked transaction.
-
-    Raises:
-        SQLAlchemyError: If the lock cannot be acquired within *timeout*.
-
-    Example:
-        ```python
-        from fastapi_toolsets.db import lock_tables, LockMode
-
-        async with lock_tables(session_maker, [User, Account]) as session:
-            # Tables are locked; changes are committed when the context exits.
-            user = await UserCrud.get(session, [User.id == 1])
-            user.balance += 100
-
-        # With custom lock mode
-        async with lock_tables(session_maker, [Order], mode=LockMode.EXCLUSIVE) as session:
-            await process_order(session, order_id)
-        ```
-    """
-    table_names = ",".join(table.__tablename__ for table in tables)
-
-    @asynccontextmanager
-    async def _lock() -> AsyncGenerator[_SessionT, None]:
-        async with session_maker() as session:
-            try:
-                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
-                await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
-                yield session
-                await session.commit()
-            except sa_exc.TimeoutError as e:
-                await session.rollback()
-                raise PoolExhaustedError(
-                    f"Connection pool exhausted while locking '{table_names}'. "
-                ) from e
-            except sa_exc.DBAPIError as e:
-                await session.rollback()
-                if _is_lock_not_available(e):
-                    raise LockTimeoutError(
-                        f"Lock on '{table_names}' could not be acquired within {timeout}."
-                    ) from e
-                raise  # pragma: no cover
-            except BaseException:
-                await session.rollback()
-                raise
-
-    return _lock()
-
-
-@asynccontextmanager
-async def advisory_lock(
-    session: AsyncSession,
-    key: int | tuple[int, int],
-    *,
-    shared: bool = False,
-    nowait: bool = False,
-    timeout: str | None = None,
-) -> AsyncGenerator[bool, None]:
-    """Acquire a PostgreSQL session-level advisory lock.
-
-    Args:
-        session: AsyncSession instance.
-        key: Lock key — a single ``int`` (bigint) or a ``(int, int)`` pair for namespacing.
-        shared: Acquire a shared lock (multiple holders allowed). Default is exclusive.
-        nowait: Return ``False`` immediately if the lock is unavailable instead of waiting.
-        timeout: Maximum wait time (e.g. ``"5s"``, ``"500ms"``). Raises ``DBAPIError``
-            if exceeded. Ignored when *nowait* is ``True``.
-
-    Yields:
-        ``True`` if the lock was acquired, ``False`` if *nowait* is ``True`` and the lock
-        is already held.
-
-    Raises:
-        LockTimeoutError: If *timeout* is set and the lock cannot be acquired in time.
-
-    Example:
-        ```python
-        from fastapi_toolsets.db import advisory_lock
-
-        async with advisory_lock(session, 42):
-            ...
-
-        async with advisory_lock(session, 42, nowait=True) as acquired:
-            if not acquired:
-                raise HTTPException(409, "Resource is locked")
-
-        async with advisory_lock(session, 42, timeout="5s"):
-            ...
-
-        async with advisory_lock(session, (1, user_id), shared=True):
-            ...
-        ```
-    """
-    suffix = "_shared" if shared else ""
-    acquire_fn = f"{'pg_try_advisory_lock' if nowait else 'pg_advisory_lock'}{suffix}"
-    release_fn = f"pg_advisory_unlock{suffix}"
-
-    if isinstance(key, tuple):
-        k1, k2 = key
-        args = "CAST(:k1 AS integer), CAST(:k2 AS integer)"
-        params: dict[str, int] = {"k1": k1, "k2": k2}
-    else:
-        args = ":k"
-        params = {"k": key}
-
-    acquire_sql = text(f"SELECT {acquire_fn}({args})")
-    release_sql = text(f"SELECT {release_fn}({args})")
-
-    if timeout is not None and not nowait:
-        await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
-
-    try:
-        result = await session.execute(acquire_sql, params)
-    except sa_exc.DBAPIError as e:
-        if _is_lock_not_available(e):
-            raise LockTimeoutError(
-                f"Advisory lock {key!r} could not be acquired within {timeout}."
-            ) from e
-        raise  # pragma: no cover
-    acquired = result.scalar() if nowait else True
-    try:
-        yield acquired
-    finally:
-        if acquired:
-            await session.execute(release_sql, params)
-
-
-async def create_database(
-    db_name: str,
-    *,
-    server_url: str,
-) -> None:
-    """Create a database.
-
-    Connects to *server_url* using ``AUTOCOMMIT`` isolation and issues a
-    ``CREATE DATABASE`` statement for *db_name*.
-
-    Args:
-        db_name: Name of the database to create.
-        server_url: URL used for server-level DDL (must point to an existing
-            database on the same server).
-
-    Example:
-        ```python
-        from fastapi_toolsets.db import create_database
-
-        SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
-        await create_database("myapp_test", server_url=SERVER_URL)
-        ```
-    """
-    engine = create_async_engine(server_url, isolation_level="AUTOCOMMIT")
-    try:
-        async with engine.connect() as conn:
-            await conn.execute(text(f"CREATE DATABASE {db_name}"))
-    finally:
-        await engine.dispose()
-
-
-async def cleanup_tables(
-    session: AsyncSession,
-    base: type[DeclarativeBase],
-) -> None:
-    """Truncate all tables for fast between-test cleanup.
-
-    Executes a single ``TRUNCATE … RESTART IDENTITY CASCADE`` statement
-    across every table in *base*'s metadata, which is significantly faster
-    than dropping and re-creating tables between tests.
-
-    This is a no-op when the metadata contains no tables.
-
-    Args:
-        session: An active async database session.
-        base: SQLAlchemy DeclarativeBase class containing model metadata.
-
-    Example:
-        ```python
-        @pytest.fixture
-        async def db_session(worker_db_url):
-            async with create_db_session(worker_db_url, Base) as session:
-                yield session
-                await cleanup_tables(session, Base)
-        ```
-    """
-    tables = base.metadata.sorted_tables
-    if not tables:
-        return
-
-    table_names = ", ".join(f'"{t.name}"' for t in tables)
-    await session.execute(text(f"TRUNCATE {table_names} RESTART IDENTITY CASCADE"))
-    await session.commit()
-
-
-_M = TypeVar("_M", bound=DeclarativeBase)
-
-
-async def wait_for_row_change(
-    session: AsyncSession,
-    model: type[_M],
-    pk_value: Any,
-    *,
-    columns: list[str] | None = None,
-    interval: float = 0.5,
-    timeout: float | None = None,
-) -> _M:
-    """Poll a database row until a change is detected.
-
-    Queries the row every ``interval`` seconds and returns the model instance
-    once a change is detected in any column (or only the specified ``columns``).
-
-    Args:
-        session: AsyncSession instance
-        model: SQLAlchemy model class
-        pk_value: Primary key value of the row to watch
-        columns: Optional list of column names to watch. If None, all columns
-                 are watched.
-        interval: Polling interval in seconds (default: 0.5)
-        timeout: Maximum time to wait in seconds. None means wait forever.
-
-    Returns:
-        The refreshed model instance with updated values
-
-    Raises:
-        NotFoundError: If the row does not exist or is deleted during polling
-        TimeoutError: If timeout expires before a change is detected
-
-    Example:
-        ```python
-        from fastapi_toolsets.db import wait_for_row_change
-
-        # Wait for any column to change
-        updated = await wait_for_row_change(session, User, user_id)
-
-        # Watch specific columns with a timeout
-        updated = await wait_for_row_change(
-            session, User, user_id,
-            columns=["status", "email"],
-            interval=1.0,
-            timeout=30.0,
-        )
-        ```
-    """
-    instance = await session.get(model, pk_value)
-    if instance is None:
-        raise NotFoundError(f"{model.__name__} with pk={pk_value!r} not found")
-
-    if columns is not None:
-        watch_cols = columns
-    else:
-        watch_cols = [attr.key for attr in model.__mapper__.column_attrs]
-
-    initial = {col: getattr(instance, col) for col in watch_cols}
-
-    elapsed = 0.0
-    while True:
-        await asyncio.sleep(interval)
-        elapsed += interval
-
-        if timeout is not None and elapsed >= timeout:
-            raise TimeoutError(
-                f"No change detected on {model.__name__} "
-                f"with pk={pk_value!r} within {timeout}s"
-            )
-
-        session.expunge(instance)
-        instance = await session.get(model, pk_value)
-
-        if instance is None:
-            raise NotFoundError(f"{model.__name__} with pk={pk_value!r} was deleted")
-
-        current = {col: getattr(instance, col) for col in watch_cols}
-        if current != initial:
-            return instance
-
-
-def _m2m_prop(rel_attr: QueryableAttribute) -> RelationshipProperty:  # type: ignore[type-arg]
-    """Return the validated M2M RelationshipProperty for *rel_attr*.
-
-    Raises TypeError if *rel_attr* is not a Many-to-Many relationship.
-    """
-    prop = rel_attr.property
-    if not isinstance(prop, RelationshipProperty) or prop.secondary is None:
-        raise TypeError(
-            f"m2m helpers require a Many-to-Many relationship attribute, "
-            f"got {rel_attr!r}. Use a relationship with a secondary table."
-        )
-    return prop
-
-
-async def m2m_add(
-    session: AsyncSession,
-    instance: DeclarativeBase,
-    rel_attr: QueryableAttribute,
-    *related: DeclarativeBase,
-    ignore_conflicts: bool = False,
-) -> None:
-    """Insert rows into a Many-to-Many association table without loading the ORM collection.
-
-    Args:
-        session: DB async session.
-        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
-        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
-        *related: One or more related instances to associate with ``instance``.
-        ignore_conflicts: When ``True``, silently skip rows that already exist
-            in the association table (``ON CONFLICT DO NOTHING``).
-
-    Raises:
-        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
-    """
-    prop = _m2m_prop(rel_attr)
-    if not related:
-        return
-
-    secondary = cast(Table, prop.secondary)
-    assert secondary is not None  # guaranteed by _m2m_prop
-    sync_pairs = prop.secondary_synchronize_pairs
-    assert sync_pairs is not None  # set whenever secondary is set
-
-    # synchronize_pairs:           [(parent_col, assoc_col), ...]
-    # secondary_synchronize_pairs: [(related_col, assoc_col), ...]
-    rows: list[dict[str, Any]] = []
-    for rel_instance in related:
-        row: dict[str, Any] = {}
-        for parent_col, assoc_col in prop.synchronize_pairs:
-            row[assoc_col.name] = getattr(instance, cast(str, parent_col.key))
-        for related_col, assoc_col in sync_pairs:
-            row[assoc_col.name] = getattr(rel_instance, cast(str, related_col.key))
-        rows.append(row)
-
-    stmt = pg_insert(secondary).values(rows)
-    if ignore_conflicts:
-        stmt = stmt.on_conflict_do_nothing()
-    await session.execute(stmt)
-
-
-async def m2m_remove(
-    session: AsyncSession,
-    instance: DeclarativeBase,
-    rel_attr: QueryableAttribute,
-    *related: DeclarativeBase,
-) -> None:
-    """Remove rows from a Many-to-Many association table without loading the ORM collection.
-
-    Args:
-        session: DB async session.
-        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
-        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
-        *related: One or more related instances to disassociate from ``instance``.
-
-    Raises:
-        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
-    """
-    prop = _m2m_prop(rel_attr)
-    if not related:
-        return
-
-    secondary = cast(Table, prop.secondary)
-    assert secondary is not None  # guaranteed by _m2m_prop
-    related_pairs = prop.secondary_synchronize_pairs
-    assert related_pairs is not None  # set whenever secondary is set
-
-    parent_where = [
-        assoc_col == getattr(instance, cast(str, parent_col.key))
-        for parent_col, assoc_col in prop.synchronize_pairs
-    ]
-
-    if len(related_pairs) == 1:
-        related_col, assoc_col = related_pairs[0]
-        related_values = [getattr(r, cast(str, related_col.key)) for r in related]
-        related_where = assoc_col.in_(related_values)
-    else:
-        assoc_cols = [ac for _, ac in related_pairs]
-        rel_cols = [rc for rc, _ in related_pairs]
-        related_values_t = [
-            tuple(getattr(r, cast(str, rc.key)) for rc in rel_cols) for r in related
-        ]
-        related_where = tuple_(*assoc_cols).in_(related_values_t)
-
-    await session.execute(delete(secondary).where(*parent_where, related_where))
-
-
-async def m2m_set(
-    session: AsyncSession,
-    instance: DeclarativeBase,
-    rel_attr: QueryableAttribute,
-    *related: DeclarativeBase,
-) -> None:
-    """Replace the entire Many-to-Many association set atomically.
-
-    Args:
-        session: DB async session.
-        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
-        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
-        *related: The new complete set of related instances.
-
-    Raises:
-        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
-    """
-    prop = _m2m_prop(rel_attr)
-    secondary = cast(Table, prop.secondary)
-    assert secondary is not None  # guaranteed by _m2m_prop
-
-    parent_where = [
-        assoc_col == getattr(instance, cast(str, parent_col.key))
-        for parent_col, assoc_col in prop.synchronize_pairs
-    ]
-    await session.execute(delete(secondary).where(*parent_where))
-
-    if related:
-        await m2m_add(session, instance, rel_attr, *related)
@@ -0,0 +1,18 @@
+"""Database package: the ``Database`` facade plus PostgreSQL power-tools."""
+
+from .core import Database, transaction
+from .locks import LockMode, advisory_lock, lock_tables
+from .m2m import m2m_add, m2m_remove, m2m_set
+from .watch import wait_for_row_change
+
+__all__ = [
+    "Database",
+    "LockMode",
+    "advisory_lock",
+    "lock_tables",
+    "m2m_add",
+    "m2m_remove",
+    "m2m_set",
+    "transaction",
+    "wait_for_row_change",
+]
@@ -0,0 +1,315 @@
+"""The ``Database`` facade: session lifecycle, dependency, middleware, transactions."""
+
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import Any
+
+from sqlalchemy import exc as sa_exc
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+from starlette.requests import Request
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ..exceptions import PoolExhaustedError
+from .locks import LockMode, lock_tables
+
+
+@asynccontextmanager
+async def transaction(
+    session: AsyncSession,
+) -> AsyncGenerator[AsyncSession, None]:
+    """Run a block inside a savepoint-aware transaction.
+
+    If *session* is already in a transaction, a nested transaction (savepoint)
+    is opened so the block can roll back independently. Otherwise a top-level
+    transaction is started. Commits on clean exit, rolls back on exception.
+
+    Args:
+        session: AsyncSession instance.
+
+    Yields:
+        The session within the transaction context.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import transaction
+
+        async with transaction(session):
+            session.add(model)
+        ```
+    """
+    if session.in_transaction():
+        async with session.begin_nested():
+            yield session
+    else:
+        async with session.begin():
+            yield session
+
+
+class _CommitOnResponseMiddleware:
+    """Commit the request's DB session before the response is sent."""
+
+    def __init__(self, app: ASGIApp, *, state_attr: str) -> None:
+        self.app = app
+        self.state_attr = state_attr
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                # ``scope["state"]`` is the same dict ``request.state`` writes
+                # to, so this is the session stashed by the dependency.
+                state = scope.get("state")
+                session = state.get(self.state_attr) if state else None
+                if session is not None and session.in_transaction():
+                    await session.commit()
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+
+class Database:
+    """One object that owns the engine, sessions, dependency, and middleware.
+
+    Provide exactly one of *url* (the facade builds and disposes the engine) or
+    *engine* (an engine you own, e.g. for Alembic or ``event.listen``, left
+    untouched).
+
+    Args:
+        url: Database connection URL (e.g. ``"postgresql+asyncpg://..."``).
+        engine: An existing :class:`AsyncEngine` to reuse instead of *url*.
+        session_class: Session class for the sessionmaker (e.g. ``EventSession``).
+        expire_on_commit: Expire attributes after commit. Defaults to ``False``.
+        autoflush: Autoflush the session before queries. Defaults to ``True``.
+        **engine_options: Extra keyword arguments forwarded to
+            :func:`create_async_engine` (URL mode only, e.g. ``pool_size``,
+            ``echo``, ``connect_args``).
+
+    Raises:
+        TypeError: If neither or both of *url* and *engine* are given, or if
+            *engine_options* are passed together with *engine*.
+
+    Example:
+        ```python
+        from fastapi import Depends, FastAPI
+        from fastapi_toolsets.db import Database
+
+        db = Database("postgresql+asyncpg://postgres:postgres@localhost/app")
+
+        app = FastAPI()
+        db.install(app)
+
+        @app.get("/users/{user_id}")
+        async def get_user(user_id: int, session=Depends(db)):
+            return await UserCrud.get(session, [User.id == user_id])
+        ```
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        *,
+        engine: AsyncEngine | None = None,
+        session_class: type[AsyncSession] = AsyncSession,
+        expire_on_commit: bool = False,
+        autoflush: bool = True,
+        **engine_options: Any,
+    ) -> None:
+        if (url is None) == (engine is None):
+            raise TypeError(
+                "Database requires exactly one of 'url' or 'engine' "
+                "(got both or neither)."
+            )
+        if engine is not None and engine_options:
+            raise TypeError(
+                "engine_options are only valid in URL mode; configure the "
+                "engine you pass via 'engine=' yourself."
+            )
+
+        if engine is not None:
+            self._owns_engine = False
+            self.engine: AsyncEngine = engine
+        else:
+            assert url is not None  # guaranteed by the XOR check above
+            self._owns_engine = True
+            self.engine = create_async_engine(url, **engine_options)
+        self._sessionmaker: async_sessionmaker[AsyncSession] = async_sessionmaker(
+            self.engine,
+            class_=session_class,
+            expire_on_commit=expire_on_commit,
+            autoflush=autoflush,
+        )
+        # Private, per-instance state attribute; cannot collide with another
+        # Database or be mismatched against the middleware.
+        self._state_attr = f"_ft_db_session_{id(self):x}"
+        self._middleware_installed = False
+        self._disposed = False
+
+    async def _dispose(self) -> None:
+        """Dispose the engine once, only if we own it (idempotent)."""
+        if self._owns_engine and not self._disposed:
+            self._disposed = True
+            await self.engine.dispose()
+
+    @asynccontextmanager
+    async def lifespan(self, app: Any) -> AsyncGenerator[None, None]:
+        """Dispose the engine on shutdown; use as ``FastAPI(lifespan=db.lifespan)``.
+
+        Args:
+            app: The ASGI application (unused; required by the lifespan protocol).
+
+        Yields:
+            Control to the application for its lifetime.
+
+        Example:
+            ```python
+            app = FastAPI(lifespan=db.lifespan)
+            ```
+        """
+        try:
+            yield
+        finally:
+            await self._dispose()
+
+    def install(self, app: Any) -> None:
+        """Wire the commit middleware and engine disposal onto *app*.
+
+        Args:
+            app: The FastAPI/Starlette application to wire.
+
+        Example:
+            ```python
+            @asynccontextmanager
+            async def lifespan(app):
+                ...  # your startup
+                yield
+                ...  # your shutdown
+
+            app = FastAPI(lifespan=lifespan)
+            db.install(app)
+            ```
+        """
+        app.add_middleware(_CommitOnResponseMiddleware, state_attr=self._state_attr)
+        self._middleware_installed = True
+
+        inner_lifespan = app.router.lifespan_context
+
+        @asynccontextmanager
+        async def _composed(app_: Any) -> AsyncGenerator[None, None]:
+            async with self.lifespan(app_):
+                async with inner_lifespan(app_):
+                    yield
+
+        app.router.lifespan_context = _composed
+
+    @asynccontextmanager
+    async def _open(self) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session and eagerly acquire a connection (fail-fast on pool)."""
+        async with self._sessionmaker() as session:
+            try:
+                await session.connection()
+            except sa_exc.TimeoutError as e:
+                raise PoolExhaustedError() from e
+            yield session
+
+    async def __call__(self, request: Request) -> AsyncGenerator[AsyncSession, None]:
+        """FastAPI dependency: yield a session and commit once at the right time.
+
+        Args:
+            request: The incoming request (injected by FastAPI).
+
+        Yields:
+            An AsyncSession for the duration of the request.
+
+        Example:
+            ```python
+            @app.get("/users/{user_id}")
+            async def get_user(user_id: int, session=Depends(db)):
+                return await UserCrud.get(session, [User.id == user_id])
+            ```
+        """
+        async with self._open() as session:
+            setattr(request.state, self._state_attr, session)
+            yield session
+            if not self._middleware_installed and session.in_transaction():
+                await session.commit()
+
+    @asynccontextmanager
+    async def session(self) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session outside request handlers (background tasks, CLI, tests).
+
+        Commits on clean exit, rolls back on exception.
+
+        Yields:
+            An AsyncSession ready for database operations.
+
+        Example:
+            ```python
+            async with db.session() as session:
+                user = await UserCrud.get(session, [User.id == 1])
+            ```
+        """
+        async with self._open() as session:
+            yield session
+            if session.in_transaction():
+                await session.commit()
+
+    @asynccontextmanager
+    async def begin(self) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session already inside a transaction (sugar for the common case).
+
+        Equivalent to ``session()`` + :func:`transaction`. Commits on clean exit,
+        rolls back on exception.
+
+        Yields:
+            An AsyncSession open within a transaction.
+
+        Example:
+            ```python
+            async with db.begin() as session:
+                session.add(User(name="ada"))
+            ```
+        """
+        async with self.session() as session, transaction(session):
+            yield session
+
+    def lock_tables(
+        self,
+        tables: list[type[DeclarativeBase]],
+        *,
+        mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
+        timeout: str = "5s",
+    ) -> AbstractAsyncContextManager[AsyncSession]:
+        """Lock PostgreSQL tables for the duration of a dedicated transaction.
+
+        Opens its own session from the facade's sessionmaker, changes are
+        committed when the context exits.
+
+        Args:
+            tables: List of SQLAlchemy model classes to lock.
+            mode: Lock mode (default: ``SHARE UPDATE EXCLUSIVE``).
+            timeout: Lock timeout (default: ``"5s"``).
+
+        Yields:
+            The dedicated session, open within the locked transaction.
+
+        Raises:
+            LockTimeoutError: If the lock cannot be acquired within *timeout*.
+            PoolExhaustedError: If the connection pool is exhausted.
+
+        Example:
+            ```python
+            async with db.lock_tables([User, Account]) as session:
+                user = await UserCrud.get(session, [User.id == 1])
+                user.balance += 100
+            ```
+        """
+        return lock_tables(self._sessionmaker, tables, mode=mode, timeout=timeout)
@@ -0,0 +1,185 @@
+"""PostgreSQL locking helpers: table locks and advisory locks."""
+
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from enum import Enum
+from typing import TypeVar
+
+import asyncpg
+from sqlalchemy import exc as sa_exc
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+from ..exceptions import LockTimeoutError, PoolExhaustedError
+
+_SessionT = TypeVar("_SessionT", bound=AsyncSession)
+
+
+def _is_lock_not_available(e: sa_exc.DBAPIError) -> bool:
+    return e.orig is not None and isinstance(
+        e.orig.__cause__, asyncpg.exceptions.LockNotAvailableError
+    )
+
+
+class LockMode(str, Enum):
+    """PostgreSQL table lock modes.
+
+    See: https://www.postgresql.org/docs/current/explicit-locking.html
+    """
+
+    ACCESS_SHARE = "ACCESS SHARE"
+    ROW_SHARE = "ROW SHARE"
+    ROW_EXCLUSIVE = "ROW EXCLUSIVE"
+    SHARE_UPDATE_EXCLUSIVE = "SHARE UPDATE EXCLUSIVE"
+    SHARE = "SHARE"
+    SHARE_ROW_EXCLUSIVE = "SHARE ROW EXCLUSIVE"
+    EXCLUSIVE = "EXCLUSIVE"
+    ACCESS_EXCLUSIVE = "ACCESS EXCLUSIVE"
+
+
+def lock_tables(
+    session_maker: async_sessionmaker[_SessionT],
+    tables: list[type[DeclarativeBase]],
+    *,
+    mode: LockMode = LockMode.SHARE_UPDATE_EXCLUSIVE,
+    timeout: str = "5s",
+) -> AbstractAsyncContextManager[_SessionT]:
+    """Lock PostgreSQL tables for the duration of a transaction.
+
+    Prefer the method on a :class:`Database` instance; use this
+    directly only when you manage your own session factory.
+
+    Args:
+        session_maker: Async session factory used to create the dedicated
+            session.
+        tables: List of SQLAlchemy model classes to lock.
+        mode: Lock mode (default: SHARE UPDATE EXCLUSIVE).
+        timeout: Lock timeout (default: "5s").
+
+    Yields:
+        The dedicated session, open within the locked transaction.
+
+    Raises:
+        LockTimeoutError: If the lock cannot be acquired within *timeout*.
+        PoolExhaustedError: If the connection pool is exhausted.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import lock_tables
+
+        async with lock_tables(session_maker, [User, Account]) as session:
+            user = await UserCrud.get(session, [User.id == 1])
+            user.balance += 100
+        ```
+    """
+    table_names = ",".join(table.__tablename__ for table in tables)
+
+    @asynccontextmanager
+    async def _lock() -> AsyncGenerator[_SessionT, None]:
+        async with session_maker() as session:
+            try:
+                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
+                await session.execute(text(f"LOCK {table_names} IN {mode.value} MODE"))
+                yield session
+                await session.commit()
+            except sa_exc.TimeoutError as e:
+                await session.rollback()
+                raise PoolExhaustedError(
+                    f"Connection pool exhausted while locking '{table_names}'. "
+                ) from e
+            except sa_exc.DBAPIError as e:
+                await session.rollback()
+                if _is_lock_not_available(e):
+                    raise LockTimeoutError(
+                        f"Lock on '{table_names}' could not be acquired within {timeout}."
+                    ) from e
+                raise  # pragma: no cover
+            except BaseException:
+                await session.rollback()
+                raise
+
+    return _lock()
+
+
+@asynccontextmanager
+async def advisory_lock(
+    session: AsyncSession,
+    key: int | tuple[int, int],
+    *,
+    shared: bool = False,
+    nowait: bool = False,
+    timeout: str | None = None,
+) -> AsyncGenerator[bool, None]:
+    """Acquire a PostgreSQL session-level advisory lock.
+
+    Args:
+        session: AsyncSession instance.
+        key: Lock key, either a single ``int`` (bigint) or a ``(int, int)`` pair for namespacing.
+        shared: Acquire a shared lock (multiple holders allowed). Default is exclusive.
+        nowait: Return ``False`` immediately if the lock is unavailable instead of waiting.
+        timeout: Maximum wait time (e.g. ``"5s"``, ``"500ms"``). Raises ``DBAPIError``
+            if exceeded. Ignored when *nowait* is ``True``.
+
+    Yields:
+        ``True`` if the lock was acquired, ``False`` if *nowait* is ``True`` and the lock
+        is already held.
+
+    Raises:
+        LockTimeoutError: If *timeout* is set and the lock cannot be acquired in time.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import advisory_lock
+
+        async with advisory_lock(session, 42):
+            ...
+
+        async with advisory_lock(session, 42, nowait=True) as acquired:
+            if not acquired:
+                raise HTTPException(409, "Resource is locked")
+
+        async with advisory_lock(session, 42, timeout="5s"):
+            ...
+
+        async with advisory_lock(session, (1, user_id), shared=True):
+            ...
+        ```
+    """
+    suffix = "_shared" if shared else ""
+    acquire_fn = f"{'pg_try_advisory_lock' if nowait else 'pg_advisory_lock'}{suffix}"
+    release_fn = f"pg_advisory_unlock{suffix}"
+
+    if isinstance(key, tuple):
+        k1, k2 = key
+        args = "CAST(:k1 AS integer), CAST(:k2 AS integer)"
+        params: dict[str, int] = {"k1": k1, "k2": k2}
+    else:
+        args = ":k"
+        params = {"k": key}
+
+    acquire_sql = text(f"SELECT {acquire_fn}({args})")
+    release_sql = text(f"SELECT {release_fn}({args})")
+
+    # Lock management runs raw SQL on the caller's session. Guard it with
+    # ``no_autoflush`` so acquiring or releasing the lock never flushes the
+    # caller's pending ORM changes; SQLAlchemy 2.1 autoflushes on raw
+    # ``text()`` too, where 2.0 did not.
+    try:
+        with session.no_autoflush:
+            if timeout is not None and not nowait:
+                await session.execute(text(f"SET LOCAL lock_timeout='{timeout}'"))
+            result = await session.execute(acquire_sql, params)
+    except sa_exc.DBAPIError as e:
+        if _is_lock_not_available(e):
+            raise LockTimeoutError(
+                f"Advisory lock {key!r} could not be acquired within {timeout}."
+            ) from e
+        raise  # pragma: no cover
+    acquired = result.scalar() if nowait else True
+    try:
+        yield acquired
+    finally:
+        if acquired:
+            with session.no_autoflush:
+                await session.execute(release_sql, params)
@@ -0,0 +1,170 @@
+"""Many-to-Many association-table helpers (direct, without loading collections)."""
+
+from typing import Any, TypeVar, cast
+
+from sqlalchemy import ColumnElement, Table, delete, tuple_
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
+from sqlalchemy.orm.relationships import RelationshipProperty
+
+_M = TypeVar("_M", bound=DeclarativeBase)
+
+
+def _m2m_prop(rel_attr: QueryableAttribute) -> tuple[RelationshipProperty, Table]:  # type: ignore[type-arg]
+    """Return the validated M2M RelationshipProperty and its secondary table.
+
+    Raises TypeError if *rel_attr* is not a Many-to-Many relationship.
+    """
+    prop = rel_attr.property
+    if not isinstance(prop, RelationshipProperty) or prop.secondary is None:
+        raise TypeError(
+            f"m2m helpers require a Many-to-Many relationship attribute, "
+            f"got {rel_attr!r}. Use a relationship with a secondary table."
+        )
+    return prop, cast(Table, prop.secondary)
+
+
+def _parent_where(
+    prop: RelationshipProperty,  # type: ignore[type-arg]
+    instance: DeclarativeBase,
+) -> list[ColumnElement[bool]]:
+    """Build the WHERE clauses matching the owner side of *instance*."""
+    return [
+        assoc_col == getattr(instance, cast(str, parent_col.key))
+        for parent_col, assoc_col in prop.synchronize_pairs
+    ]
+
+
+async def m2m_add(
+    session: AsyncSession,
+    instance: DeclarativeBase,
+    rel_attr: QueryableAttribute,
+    *related: DeclarativeBase,
+    ignore_conflicts: bool = False,
+) -> None:
+    """Insert rows into a Many-to-Many association table without loading the ORM collection.
+
+    Args:
+        session: DB async session.
+        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
+        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
+        *related: One or more related instances to associate with ``instance``.
+        ignore_conflicts: When ``True``, silently skip rows that already exist
+            in the association table (``ON CONFLICT DO NOTHING``).
+
+    Raises:
+        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import m2m_add, transaction
+
+        async with transaction(session):
+            await m2m_add(session, post, Post.tags, tag1, tag2)
+        ```
+    """
+    prop, secondary = _m2m_prop(rel_attr)
+    if not related:
+        return
+
+    sync_pairs = prop.secondary_synchronize_pairs
+    assert sync_pairs is not None  # set whenever secondary is set
+
+    # synchronize_pairs:           [(parent_col, assoc_col), ...]
+    # secondary_synchronize_pairs: [(related_col, assoc_col), ...]
+    rows: list[dict[str, Any]] = []
+    for rel_instance in related:
+        row: dict[str, Any] = {}
+        for parent_col, assoc_col in prop.synchronize_pairs:
+            row[assoc_col.name] = getattr(instance, cast(str, parent_col.key))
+        for related_col, assoc_col in sync_pairs:
+            row[assoc_col.name] = getattr(rel_instance, cast(str, related_col.key))
+        rows.append(row)
+
+    stmt = pg_insert(secondary).values(rows)
+    if ignore_conflicts:
+        stmt = stmt.on_conflict_do_nothing()
+    await session.execute(stmt)
+
+
+async def m2m_remove(
+    session: AsyncSession,
+    instance: DeclarativeBase,
+    rel_attr: QueryableAttribute,
+    *related: DeclarativeBase,
+) -> None:
+    """Remove rows from a Many-to-Many association table without loading the ORM collection.
+
+    Args:
+        session: DB async session.
+        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
+        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
+        *related: One or more related instances to disassociate from ``instance``.
+
+    Raises:
+        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import m2m_remove, transaction
+
+        async with transaction(session):
+            await m2m_remove(session, post, Post.tags, tag1)
+        ```
+    """
+    prop, secondary = _m2m_prop(rel_attr)
+    if not related:
+        return
+
+    related_pairs = prop.secondary_synchronize_pairs
+    assert related_pairs is not None  # set whenever secondary is set
+
+    parent_where = _parent_where(prop, instance)
+
+    if len(related_pairs) == 1:
+        related_col, assoc_col = related_pairs[0]
+        related_values = [getattr(r, cast(str, related_col.key)) for r in related]
+        related_where = assoc_col.in_(related_values)
+    else:
+        assoc_cols = [ac for _, ac in related_pairs]
+        rel_cols = [rc for rc, _ in related_pairs]
+        related_values_t = [
+            tuple(getattr(r, cast(str, rc.key)) for rc in rel_cols) for r in related
+        ]
+        related_where = tuple_(*assoc_cols).in_(related_values_t)
+
+    await session.execute(delete(secondary).where(*parent_where, related_where))
+
+
+async def m2m_set(
+    session: AsyncSession,
+    instance: DeclarativeBase,
+    rel_attr: QueryableAttribute,
+    *related: DeclarativeBase,
+) -> None:
+    """Replace the entire Many-to-Many association set atomically.
+
+    Args:
+        session: DB async session.
+        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
+        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
+        *related: The new complete set of related instances.
+
+    Raises:
+        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import m2m_set, transaction
+
+        async with transaction(session):
+            await m2m_set(session, post, Post.tags, tag1, tag2)  # replaces all
+        ```
+    """
+    prop, secondary = _m2m_prop(rel_attr)
+
+    await session.execute(delete(secondary).where(*_parent_where(prop, instance)))
+
+    if related:
+        await m2m_add(session, instance, rel_attr, *related)
@@ -0,0 +1,69 @@
+"""Database admin and test helpers: DDL and truncation."""
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+
+async def create_database(
+    db_name: str,
+    *,
+    server_url: str,
+) -> None:
+    """Create a database.
+
+    Connects to *server_url* using ``AUTOCOMMIT`` isolation and issues a
+    ``CREATE DATABASE`` statement for *db_name*.
+
+    Args:
+        db_name: Name of the database to create.
+        server_url: URL used for server-level DDL (must point to an existing
+            database on the same server).
+
+    Example:
+        ```python
+        from fastapi_toolsets.db.testing import create_database
+
+        SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
+        await create_database("myapp_test", server_url=SERVER_URL)
+        ```
+    """
+    engine = create_async_engine(server_url, isolation_level="AUTOCOMMIT")
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text(f"CREATE DATABASE {db_name}"))
+    finally:
+        await engine.dispose()
+
+
+async def cleanup_tables(
+    session: AsyncSession,
+    base: type[DeclarativeBase],
+) -> None:
+    """Truncate all tables for fast between-test cleanup.
+
+    Executes a single ``TRUNCATE … RESTART IDENTITY CASCADE`` statement
+    across every table in *base*'s metadata.
+
+    This is a no-op when the metadata contains no tables.
+
+    Args:
+        session: An active async database session.
+        base: SQLAlchemy DeclarativeBase class containing model metadata.
+
+    Example:
+        ```python
+        @pytest.fixture
+        async def db_session(worker_db_url):
+            async with create_db_session(worker_db_url, Base) as session:
+                yield session
+                await cleanup_tables(session, Base)
+        ```
+    """
+    tables = base.metadata.sorted_tables
+    if not tables:
+        return
+
+    table_names = ", ".join(f'"{t.name}"' for t in tables)
+    await session.execute(text(f"TRUNCATE {table_names} RESTART IDENTITY CASCADE"))
+    await session.commit()
@@ -0,0 +1,90 @@
+"""Row-watching helpers: poll a database row until it changes."""
+
+import asyncio
+from typing import Any, TypeVar
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+
+from ..exceptions import NotFoundError
+
+_M = TypeVar("_M", bound=DeclarativeBase)
+
+
+async def wait_for_row_change(
+    session: AsyncSession,
+    model: type[_M],
+    pk_value: Any,
+    *,
+    columns: list[str] | None = None,
+    interval: float = 0.5,
+    timeout: float | None = None,
+) -> _M:
+    """Poll a database row until a change is detected.
+
+    Queries the row every ``interval`` seconds and returns the model instance
+    once a change is detected in any column (or only the specified ``columns``).
+
+    Args:
+        session: AsyncSession instance.
+        model: SQLAlchemy model class.
+        pk_value: Primary key value of the row to watch.
+        columns: Optional list of column names to watch. If None, all columns
+            are watched.
+        interval: Polling interval in seconds (default: 0.5).
+        timeout: Maximum time to wait in seconds. None means wait forever.
+
+    Returns:
+        The refreshed model instance with updated values.
+
+    Raises:
+        NotFoundError: If the row does not exist or is deleted during polling.
+        TimeoutError: If timeout expires before a change is detected.
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import wait_for_row_change
+
+        # Wait for any column to change
+        updated = await wait_for_row_change(session, User, user_id)
+
+        # Watch specific columns with a timeout
+        updated = await wait_for_row_change(
+            session, User, user_id,
+            columns=["status", "email"],
+            interval=1.0,
+            timeout=30.0,
+        )
+        ```
+    """
+    instance = await session.get(model, pk_value)
+    if instance is None:
+        raise NotFoundError(f"{model.__name__} with pk={pk_value!r} not found")
+
+    if columns is not None:
+        watch_cols = columns
+    else:
+        watch_cols = [attr.key for attr in model.__mapper__.column_attrs]
+
+    initial = {col: getattr(instance, col) for col in watch_cols}
+
+    elapsed = 0.0
+    while True:
+        await asyncio.sleep(interval)
+        elapsed += interval
+
+        if timeout is not None and elapsed >= timeout:
+            raise TimeoutError(
+                f"No change detected on {model.__name__} "
+                f"with pk={pk_value!r} within {timeout}s"
+            )
+
+        session.expunge(instance)
+        instance = await session.get(model, pk_value)
+
+        if instance is None:
+            raise NotFoundError(f"{model.__name__} with pk={pk_value!r} was deleted")
+
+        current = {col: getattr(instance, col) for col in watch_cols}
+        if current != initial:
+            return instance
@@ -9,7 +9,7 @@ from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase

-from ..db import get_transaction
+from ..db import transaction
 from ..logger import get_logger
 from ..types import ModelType
 from .enum import LoadStrategy
@@ -229,7 +229,7 @@ async def _load_ordered(
        model_name = type(instances[0]).__name__
        loaded: list[DeclarativeBase] = []

-        async with get_transaction(session):
+        async with transaction(session):
            for model_cls, group in _group_by_type(instances):
                match strategy:
                    case LoadStrategy.INSERT:
@@ -9,7 +9,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase, selectinload
 from sqlalchemy.orm.interfaces import ExecutableOption, ORMOption

-from ..db import get_transaction
+from ..db import transaction
 from ..fixtures import FixtureRegistry, LoadStrategy


@@ -106,7 +106,7 @@ def _create_fixture_function(

        loaded: list[DeclarativeBase] = []

-        async with get_transaction(session):
+        async with transaction(session):
            for instance in instances:
                if strategy == LoadStrategy.INSERT:
                    session.add(instance)
@@ -7,7 +7,7 @@ from typing import Any

 from httpx import ASGITransport, AsyncClient
 from sqlalchemy import text
-from sqlalchemy.engine import make_url
+from sqlalchemy.engine import URL, make_url
 from sqlalchemy.ext.asyncio import (
    AsyncSession,
    async_sessionmaker,
@@ -15,7 +15,7 @@ from sqlalchemy.ext.asyncio import (
 )
 from sqlalchemy.orm import DeclarativeBase

-from ..db import cleanup_tables, create_database
+from ..db.testing import cleanup_tables, create_database
 from ..models.watched import EventSession


@@ -34,12 +34,18 @@ def _get_xdist_worker(default_test_db: str) -> str:
    return os.environ.get("PYTEST_XDIST_WORKER", default_test_db)


-def worker_database_url(database_url: str, default_test_db: str) -> str:
+def worker_database_url(
+    database_url: str,
+    default_test_db: str,
+    *,
+    prefix: str | None = None,
+) -> str:
    """Derive a per-worker database URL for pytest-xdist parallel runs.

-    Appends ``_{worker_name}`` to the database name so each xdist worker
-    operates on its own database.  When not running under xdist,
-    ``_{default_test_db}`` is appended instead.
+    Sets the database name to the worker name so each xdist worker operates
+    on its own database.  When not running under xdist, *default_test_db* is
+    used instead.  When *prefix* is provided, the name becomes
+    ``{prefix}_{worker}``.

    The worker name is read from the ``PYTEST_XDIST_WORKER`` environment
    variable (set automatically by xdist in each worker process).
@@ -48,6 +54,9 @@ def worker_database_url(database_url: str, default_test_db: str) -> str:
        database_url: Original database connection URL.
        default_test_db: Suffix appended to the database name when
            ``PYTEST_XDIST_WORKER`` is not set.
+        prefix: Optional prefix prepended to the worker name
+            (e.g. ``"test"`` → ``"test_gw0"``).  Without it, the database
+            name is just the worker name (e.g. ``"gw0"``).

    Returns:
        A database URL with a worker- or default-specific database name.
@@ -55,7 +64,8 @@ def worker_database_url(database_url: str, default_test_db: str) -> str:
    worker = _get_xdist_worker(default_test_db=default_test_db)

    url = make_url(database_url)
-    url = url.set(database=f"{url.database}_{worker}")
+    db_name = f"{prefix}_{worker}" if prefix else worker
+    url = url.set(database=db_name)
    return url.render_as_string(hide_password=False)


@@ -63,6 +73,9 @@ def worker_database_url(database_url: str, default_test_db: str) -> str:
 async def create_worker_database(
    database_url: str,
    default_test_db: str = "test_db",
+    *,
+    prefix: str | None = None,
+    server_url: str | None = None,
 ) -> AsyncGenerator[str, None]:
    """Create and drop a per-worker database for pytest-xdist isolation.

@@ -74,10 +87,16 @@ async def create_worker_database(
    name (e.g. ``_gw0``).  Otherwise it is suffixed with *default_test_db*.

    Args:
-        database_url: Original database connection URL (used as the server
-            connection and as the base for the worker database name).
+        database_url: Original database connection URL (used as the base for
+            the worker database name).
        default_test_db: Suffix appended to the database name when
            ``PYTEST_XDIST_WORKER`` is not set. Defaults to ``"test_db"``.
+        prefix: Optional prefix prepended to the worker name
+            (e.g. ``prefix="test"`` → ``"test_gw0"``).  Without it, the
+            database name is just the worker name (e.g. ``"gw0"``).
+        server_url: URL used for server-level DDL (must point to an existing
+            database on the same server).  Defaults to *database_url* with the
+            database omitted, letting asyncpg fall back to the username.

    Yields:
        The worker-specific database URL.
@@ -86,7 +105,7 @@ async def create_worker_database(
        ```python
        from fastapi_toolsets.pytest import create_worker_database, create_db_session

-        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/test_db"
+        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/myapp"

        @pytest.fixture(scope="session")
        async def worker_db_url():
@@ -102,21 +121,35 @@ async def create_worker_database(
        ```
    """
    worker_url = worker_database_url(
-        database_url=database_url, default_test_db=default_test_db
+        database_url=database_url, default_test_db=default_test_db, prefix=prefix
    )
    worker_db_name = make_url(worker_url).database
    assert worker_db_name is not None

-    engine = create_async_engine(database_url, isolation_level="AUTOCOMMIT")
+    _parsed = make_url(database_url)
+    _server_url = server_url or URL.create(
+        drivername=_parsed.drivername,
+        username=_parsed.username,
+        password=_parsed.password,
+        host=_parsed.host,
+        port=_parsed.port,
+        query=_parsed.query,
+    ).render_as_string(hide_password=False)
+
+    engine = create_async_engine(_server_url, isolation_level="AUTOCOMMIT")
    try:
        async with engine.connect() as conn:
-            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
-        await create_database(db_name=worker_db_name, server_url=database_url)
+            await conn.execute(
+                text(f"DROP DATABASE IF EXISTS {worker_db_name} WITH (FORCE)")
+            )
+        await create_database(db_name=worker_db_name, server_url=_server_url)

        yield worker_url

        async with engine.connect() as conn:
-            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
+            await conn.execute(
+                text(f"DROP DATABASE IF EXISTS {worker_db_name} WITH (FORCE)")
+            )
    finally:
        await engine.dispose()

@@ -126,6 +159,7 @@ async def create_async_client(
    app: Any,
    base_url: str = "http://test",
    dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] | None = None,
+    **kwargs: Any,
 ) -> AsyncGenerator[AsyncClient, None]:
    """Create an async httpx client for testing FastAPI applications.

@@ -135,6 +169,9 @@ async def create_async_client(
        dependency_overrides: Optional mapping of original dependencies to
            their test replacements. Applied via ``app.dependency_overrides``
            before yielding and cleaned up after.
+        **kwargs: Additional keyword arguments forwarded to
+            :class:`httpx.AsyncClient` (e.g. ``headers``, ``cookies``,
+            ``auth``, ``timeout``).

    Yields:
        An AsyncClient configured for the app.
@@ -182,7 +219,9 @@ async def create_async_client(

    transport = ASGITransport(app=app)
    try:
-        async with AsyncClient(transport=transport, base_url=base_url) as client:
+        async with AsyncClient(
+            transport=transport, base_url=base_url, **kwargs
+        ) as client:
            yield client
    finally:
        if dependency_overrides:
@@ -199,6 +238,8 @@ async def create_db_session(
    expire_on_commit: bool = False,
    drop_tables: bool = True,
    cleanup: bool = False,
+    engine_kwargs: dict[str, Any] | None = None,
+    session_kwargs: dict[str, Any] | None = None,
 ) -> AsyncGenerator[AsyncSession, None]:
    """Create a database session for testing.

@@ -213,6 +254,12 @@ async def create_db_session(
        drop_tables: Drop tables after test. Defaults to True.
        cleanup: Truncate all tables after test using
            :func:`cleanup_tables`. Defaults to False.
+        engine_kwargs: Additional keyword arguments forwarded to
+            :func:`sqlalchemy.ext.asyncio.create_async_engine`
+            (e.g. ``pool_size``, ``connect_args``).
+        session_kwargs: Additional keyword arguments forwarded to
+            :class:`sqlalchemy.ext.asyncio.async_sessionmaker`
+            (e.g. ``autoflush``, ``class_``).

    Yields:
        An AsyncSession ready for database operations.
@@ -237,15 +284,17 @@ async def create_db_session(
            await db_session.commit()
        ```
    """
-    engine = create_async_engine(database_url, echo=echo)
+    engine = create_async_engine(database_url, echo=echo, **(engine_kwargs or {}))

    try:
-        # Create tables
        async with engine.begin() as conn:
            await conn.run_sync(base.metadata.create_all)

        session_maker = async_sessionmaker(
-            engine, expire_on_commit=expire_on_commit, class_=EventSession
+            engine,
+            expire_on_commit=expire_on_commit,
+            class_=EventSession,
+            **(session_kwargs or {}),
        )
        async with session_maker() as session:
            yield session
@@ -91,13 +91,19 @@ async def seed(session: AsyncSession):
 class TestAppSessionDep:
    @pytest.mark.anyio
    async def test_get_db_yields_async_session(self):
-        """get_db yields a real AsyncSession when called directly."""
-        from docs_src.examples.pagination_search.db import get_db
+        """The Database dependency yields a real AsyncSession when called directly."""
+        from starlette.requests import Request

-        gen = get_db()
-        session = await gen.__anext__()
-        assert isinstance(session, AsyncSession)
-        await gen.aclose()
+        from fastapi_toolsets.db import Database
+
+        db = Database(DATABASE_URL)
+        try:
+            gen = db(Request({"type": "http", "headers": []}))
+            session = await gen.__anext__()
+            assert isinstance(session, AsyncSession)
+            await gen.aclose()
+        finally:
+            await db.engine.dispose()


 class TestOffsetPagination:
@@ -1506,8 +1506,8 @@ class TestListensFor:
        assert all(e["event"] == "change" for e in _listener_events)


-class TestEventSessionWithGetTransaction:
-    """Verify callbacks fire correctly when using get_transaction / lock_tables."""
+class TestEventSessionWithTransaction:
+    """Verify callbacks fire correctly when using transaction / lock_tables."""

    @pytest.fixture(autouse=True)
    def clear_events(self):
@@ -1517,10 +1517,10 @@ class TestEventSessionWithGetTransaction:

    @pytest.mark.anyio
    async def test_callbacks_fire_after_outer_commit_not_savepoint(self, mixin_session):
-        """get_transaction creates a savepoint; callbacks fire only on outer commit."""
-        from fastapi_toolsets.db import get_transaction
+        """transaction creates a savepoint; callbacks fire only on outer commit."""
+        from fastapi_toolsets.db import transaction

-        async with get_transaction(mixin_session):
+        async with transaction(mixin_session):
            obj = WatchedModel(status="active", other="x")
            mixin_session.add(obj)

@@ -1535,14 +1535,14 @@ class TestEventSessionWithGetTransaction:

    @pytest.mark.anyio
    async def test_nested_transactions_accumulate_events(self, mixin_session):
-        """Multiple get_transaction blocks accumulate events for a single commit."""
-        from fastapi_toolsets.db import get_transaction
+        """Multiple transaction blocks accumulate events for a single commit."""
+        from fastapi_toolsets.db import transaction

-        async with get_transaction(mixin_session):
+        async with transaction(mixin_session):
            obj1 = WatchedModel(status="first", other="x")
            mixin_session.add(obj1)

-        async with get_transaction(mixin_session):
+        async with transaction(mixin_session):
            obj2 = WatchedModel(status="second", other="y")
            mixin_session.add(obj2)

@@ -1556,14 +1556,14 @@ class TestEventSessionWithGetTransaction:
    @pytest.mark.anyio
    async def test_savepoint_rollback_suppresses_events(self, mixin_session):
        """Objects from a rolled-back savepoint don't fire callbacks."""
-        from fastapi_toolsets.db import get_transaction
+        from fastapi_toolsets.db import transaction

        survivor = WatchedModel(status="kept", other="x")
        mixin_session.add(survivor)
        await mixin_session.flush()

        try:
-            async with get_transaction(mixin_session):
+            async with transaction(mixin_session):
                doomed = WatchedModel(status="doomed", other="y")
                mixin_session.add(doomed)
                await mixin_session.flush()
@@ -1590,9 +1590,9 @@ class TestEventSessionWithGetTransaction:
        assert len(creates) == 1

    @pytest.mark.anyio
-    async def test_update_inside_get_transaction(self, mixin_session):
-        """UPDATE events fire with correct changes after get_transaction commit."""
-        from fastapi_toolsets.db import get_transaction
+    async def test_update_inside_transaction(self, mixin_session):
+        """UPDATE events fire with correct changes after transaction commit."""
+        from fastapi_toolsets.db import transaction

        obj = WatchedModel(status="initial", other="x")
        mixin_session.add(obj)
@@ -1600,7 +1600,7 @@ class TestEventSessionWithGetTransaction:

        _test_events.clear()

-        async with get_transaction(mixin_session):
+        async with transaction(mixin_session):
            obj.status = "updated"

        await mixin_session.commit()
@@ -1696,7 +1696,7 @@ class TestEventSessionWithNullableFields:


 class TestEventSessionWithFastAPIDependency:
-    """Verify EventSession works when session comes from create_db_dependency."""
+    """Verify EventSession works when session comes from the Database dependency."""

    @pytest.fixture(autouse=True)
    def clear_events(self):
@@ -1706,31 +1706,24 @@ class TestEventSessionWithFastAPIDependency:

    @pytest.mark.anyio
    async def test_create_event_fires_via_dependency(self):
-        """CREATE callback fires when session is provided by create_db_dependency."""
+        """CREATE callback fires when session is provided by the Database dependency."""
        from fastapi import Depends, FastAPI
        from httpx import ASGITransport, AsyncClient
-        from sqlalchemy.ext.asyncio import (
-            AsyncSession,
-            async_sessionmaker,
-            create_async_engine,
-        )
+        from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine

-        from fastapi_toolsets.db import create_db_dependency
+        from fastapi_toolsets.db import Database
        from fastapi_toolsets.models import EventSession

        engine = create_async_engine(DATABASE_URL, echo=False)
-        session_factory = async_sessionmaker(
-            engine, expire_on_commit=False, class_=EventSession
-        )

        async with engine.begin() as conn:
            await conn.run_sync(MixinBase.metadata.create_all)

-        get_db = create_db_dependency(session_factory)
+        db = Database(engine=engine, session_class=EventSession)
        app = FastAPI()

        @app.post("/watched")
-        async def create_watched(session: AsyncSession = Depends(get_db)):
+        async def create_watched(session: AsyncSession = Depends(db)):
            obj = WatchedModel(status="from-api", other="x")
            session.add(obj)
            return {"id": str(obj.id)}
@@ -1753,40 +1746,33 @@ class TestEventSessionWithFastAPIDependency:

    @pytest.mark.anyio
    async def test_update_event_fires_via_dependency(self):
-        """UPDATE callback fires when session is provided by create_db_dependency."""
+        """UPDATE callback fires when session is provided by the Database dependency."""
        from fastapi import Depends, FastAPI
        from httpx import ASGITransport, AsyncClient
-        from sqlalchemy.ext.asyncio import (
-            AsyncSession,
-            async_sessionmaker,
-            create_async_engine,
-        )
+        from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine

-        from fastapi_toolsets.db import create_db_dependency
+        from fastapi_toolsets.db import Database
        from fastapi_toolsets.models import EventSession

        engine = create_async_engine(DATABASE_URL, echo=False)
-        session_factory = async_sessionmaker(
-            engine, expire_on_commit=False, class_=EventSession
-        )

        async with engine.begin() as conn:
            await conn.run_sync(MixinBase.metadata.create_all)

-        get_db = create_db_dependency(session_factory)
+        db = Database(engine=engine, session_class=EventSession)
        app = FastAPI()

        # Pre-seed an object.
-        async with session_factory() as seed_session:
+        async with db.session() as seed_session:
            obj = WatchedModel(status="initial", other="x")
            seed_session.add(obj)
-            await seed_session.commit()
+            await seed_session.flush()
            obj_id = obj.id

        _test_events.clear()

        @app.put("/watched/{item_id}")
-        async def update_watched(item_id: str, session: AsyncSession = Depends(get_db)):
+        async def update_watched(item_id: str, session: AsyncSession = Depends(db)):
            from sqlalchemy import select

            stmt = select(WatchedModel).where(WatchedModel.id == item_id)
@@ -11,7 +11,7 @@ from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship

-from fastapi_toolsets.db import get_transaction
+from fastapi_toolsets.db import transaction
 from fastapi_toolsets.fixtures import Context, FixtureRegistry, LoadStrategy
 from fastapi_toolsets.pytest import (
    create_async_client,
@@ -278,6 +278,21 @@ class TestCreateAsyncClient:
        # Overrides should be cleaned up
        assert original_dep not in app.dependency_overrides

+    @pytest.mark.anyio
+    async def test_kwargs_forwarded_to_async_client(self):
+        """Extra kwargs are forwarded to AsyncClient (e.g. default headers)."""
+        from fastapi import Request
+
+        app = FastAPI()
+
+        @app.get("/headers")
+        async def headers_endpoint(request: Request):
+            return {"x-custom": request.headers.get("x-custom")}
+
+        async with create_async_client(app, headers={"X-Custom": "sentinel"}) as client:
+            response = await client.get("/headers")
+            assert response.json() == {"x-custom": "sentinel"}
+

 class TestCreateDbSession:
    """Tests for create_db_session helper."""
@@ -356,14 +371,30 @@ class TestCreateDbSession:
            assert result.all() == []

    @pytest.mark.anyio
-    async def test_get_transaction_commits_visible_to_separate_session(self):
-        """Data written via get_transaction() is committed and visible to other sessions."""
+    async def test_engine_kwargs_forwarded(self):
+        """engine_kwargs are forwarded to create_async_engine."""
+        async with create_db_session(
+            DATABASE_URL, Base, engine_kwargs={"pool_pre_ping": True}
+        ) as session:
+            assert isinstance(session, AsyncSession)
+
+    @pytest.mark.anyio
+    async def test_session_kwargs_forwarded(self):
+        """session_kwargs are forwarded to async_sessionmaker."""
+        async with create_db_session(
+            DATABASE_URL, Base, session_kwargs={"autoflush": False}
+        ) as session:
+            assert session.autoflush is False
+
+    @pytest.mark.anyio
+    async def test_transaction_commits_visible_to_separate_session(self):
+        """Data written via transaction() is committed and visible to other sessions."""
        role_id = uuid.uuid4()

        async with create_db_session(DATABASE_URL, Base, drop_tables=False) as session:
-            # Simulate what _create_fixture_function does: insert via get_transaction
+            # Simulate what _create_fixture_function does: insert via transaction()
            # with no explicit commit afterward.
-            async with get_transaction(session):
+            async with transaction(session):
                role = Role(id=role_id, name="visible_to_other_session")
                session.add(role)

@@ -378,9 +409,9 @@ class TestCreateDbSession:
                    result = await other.execute(select(Role).where(Role.id == role_id))
                    fetched = result.scalar_one_or_none()
                    assert fetched is not None, (
-                        "Fixture data inserted via get_transaction() must be committed "
+                        "Fixture data inserted via transaction() must be committed "
                        "and visible to a separate session. If create_db_session uses "
-                        "create_db_context, auto-begin forces get_transaction() into "
+                        "db.session(), auto-begin forces transaction() into "
                        "savepoints instead of real commits."
                    )
                    assert fetched.name == "visible_to_other_session"
@@ -411,21 +442,19 @@ class TestGetXdistWorker:
 class TestWorkerDatabaseUrl:
    """Tests for worker_database_url helper."""

-    def test_appends_default_test_db_without_xdist(
-        self, monkeypatch: pytest.MonkeyPatch
-    ):
-        """default_test_db is appended when not running under xdist."""
+    def test_uses_default_test_db_without_xdist(self, monkeypatch: pytest.MonkeyPatch):
+        """default_test_db is used as the database name when not running under xdist."""
        monkeypatch.delenv("PYTEST_XDIST_WORKER", raising=False)
        url = "postgresql+asyncpg://user:pass@localhost:5432/mydb"
        result = worker_database_url(url, default_test_db="fallback")
-        assert make_url(result).database == "mydb_fallback"
+        assert make_url(result).database == "fallback"

-    def test_appends_worker_id_to_database_name(self, monkeypatch: pytest.MonkeyPatch):
-        """Worker name is appended to the database name."""
+    def test_uses_worker_id_as_database_name(self, monkeypatch: pytest.MonkeyPatch):
+        """Worker name is used as the database name."""
        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw0")
        url = "postgresql+asyncpg://user:pass@localhost:5432/db"
        result = worker_database_url(url, default_test_db="unused")
-        assert make_url(result).database == "db_gw0"
+        assert make_url(result).database == "gw0"

    def test_preserves_url_components(self, monkeypatch: pytest.MonkeyPatch):
        """Host, port, username, password, and driver are preserved."""
@@ -438,7 +467,21 @@ class TestWorkerDatabaseUrl:
        assert result.password == "secret"
        assert result.host == "dbhost"
        assert result.port == 6543
-        assert result.database == "testdb_gw2"
+        assert result.database == "gw2"
+
+    def test_prefix_with_xdist(self, monkeypatch: pytest.MonkeyPatch):
+        """prefix is prepended to the worker name when running under xdist."""
+        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw0")
+        url = "postgresql+asyncpg://user:pass@localhost:5432/mydb"
+        result = worker_database_url(url, default_test_db="unused", prefix="myapp")
+        assert make_url(result).database == "myapp_gw0"
+
+    def test_prefix_without_xdist(self, monkeypatch: pytest.MonkeyPatch):
+        """prefix is prepended to default_test_db when not running under xdist."""
+        monkeypatch.delenv("PYTEST_XDIST_WORKER", raising=False)
+        url = "postgresql+asyncpg://user:pass@localhost:5432/mydb"
+        result = worker_database_url(url, default_test_db="test", prefix="myapp")
+        assert make_url(result).database == "myapp_test"


 class TestCreateWorkerDatabase:
@@ -448,7 +491,7 @@ class TestCreateWorkerDatabase:
    async def test_creates_default_db_without_xdist(
        self, monkeypatch: pytest.MonkeyPatch
    ):
-        """Without xdist, creates a database suffixed with default_test_db."""
+        """Without xdist, creates a database named after default_test_db."""
        monkeypatch.delenv("PYTEST_XDIST_WORKER", raising=False)
        default_test_db = "no_xdist_default"
        expected_db = make_url(
@@ -535,6 +578,125 @@ class TestCreateWorkerDatabase:
            assert result.scalar() is None
        await engine.dispose()

+    @pytest.mark.anyio
+    async def test_works_when_database_url_db_does_not_exist(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        """Succeeds even when the database named in database_url does not exist.
+
+        Regression test: the old code connected the DDL engine to database_url
+        itself, which failed when that database had not been created yet.
+        """
+        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw_noexist")
+        nonexistent_url = (
+            make_url(DATABASE_URL)
+            .set(database="no_such_db")
+            .render_as_string(hide_password=False)
+        )
+        expected_db = make_url(
+            worker_database_url(nonexistent_url, default_test_db="unused")
+        ).database
+
+        async with create_worker_database(nonexistent_url) as url:
+            assert make_url(url).database == expected_db
+
+            engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+            async with engine.connect() as conn:
+                result = await conn.execute(
+                    text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                    {"name": expected_db},
+                )
+                assert result.scalar() == 1
+            await engine.dispose()
+
+        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+        async with engine.connect() as conn:
+            result = await conn.execute(
+                text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                {"name": expected_db},
+            )
+            assert result.scalar() is None
+        await engine.dispose()
+
+    @pytest.mark.anyio
+    async def test_explicit_server_url(self, monkeypatch: pytest.MonkeyPatch):
+        """Explicit server_url is used instead of the auto-derived one."""
+        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw_explicit_srv")
+        expected_db = make_url(
+            worker_database_url(DATABASE_URL, default_test_db="unused")
+        ).database
+
+        async with create_worker_database(DATABASE_URL, server_url=DATABASE_URL) as url:
+            assert make_url(url).database == expected_db
+
+            engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+            async with engine.connect() as conn:
+                result = await conn.execute(
+                    text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                    {"name": expected_db},
+                )
+                assert result.scalar() == 1
+            await engine.dispose()
+
+    @pytest.mark.anyio
+    async def test_drops_database_with_active_connections(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        """DROP DATABASE succeeds even when a connection is still open to it."""
+        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw_active_conn")
+        expected_db = make_url(
+            worker_database_url(DATABASE_URL, default_test_db="unused")
+        ).database
+
+        lingering_engine = None
+        async with create_worker_database(DATABASE_URL) as url:
+            # Open a connection to the worker DB and intentionally leave it open.
+            lingering_engine = create_async_engine(url)
+            async with lingering_engine.connect():
+                pass  # connection returned to pool but engine not disposed
+
+        # If WITH (FORCE) is absent the DROP above would raise; reaching here means it worked.
+        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+        async with engine.connect() as conn:
+            result = await conn.execute(
+                text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                {"name": expected_db},
+            )
+            assert result.scalar() is None
+        await engine.dispose()
+        if lingering_engine:
+            await lingering_engine.dispose()
+
+    @pytest.mark.anyio
+    async def test_prefix_names_database(self, monkeypatch: pytest.MonkeyPatch):
+        """prefix is prepended to the worker name in the created database."""
+        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw_prefix")
+        expected_db = make_url(
+            worker_database_url(DATABASE_URL, default_test_db="unused", prefix="pfx")
+        ).database
+        assert expected_db == "pfx_gw_prefix"
+
+        async with create_worker_database(DATABASE_URL, prefix="pfx") as url:
+            assert make_url(url).database == expected_db
+
+            engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+            async with engine.connect() as conn:
+                result = await conn.execute(
+                    text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                    {"name": expected_db},
+                )
+                assert result.scalar() == 1
+            await engine.dispose()
+
+        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+        async with engine.connect() as conn:
+            result = await conn.execute(
+                text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                {"name": expected_db},
+            )
+            assert result.scalar() is None
+        await engine.dispose()
+

 class _LocalBase(DeclarativeBase):
    pass
@@ -314,7 +314,7 @@ wheels = [

 [[package]]
 name = "fastapi"
-version = "0.136.1"
+version = "0.136.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "annotated-doc" },
@@ -323,14 +323,14 @@ dependencies = [
    { name = "typing-extensions" },
    { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/5d/45/c130091c2dfa061bbfe3150f2a5091ef1adf149f2a8d2ae769ecaf6e99a2/fastapi-0.136.1.tar.gz", hash = "sha256:7af665ad7acfa0a3baf8983d393b6b471b9da10ede59c60045f49fbc89a0fa7f", size = 397448, upload-time = "2026-04-23T16:49:44.046Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/81/2d/ff8d91d7b564d464629a0fd50a4489c97fcb836ac230bf3a7269232a9b1f/fastapi-0.136.3.tar.gz", hash = "sha256:e487fae93ad408e6f47641ee4dfe389864fd7bec92e547ea8498fc13f43e83ab", size = 396410, upload-time = "2026-05-23T18:53:15.192Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/5a/ff/2e4eca3ade2c22fe1dea7043b8ee9dabe47753349eb1b56a202de8af6349/fastapi-0.136.1-py3-none-any.whl", hash = "sha256:a6e9d7eeada96c93a4d69cb03836b44fa34e2854accb7244a1ece36cd4781c3f", size = 117683, upload-time = "2026-04-23T16:49:42.437Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/82/45359b62a067409bd929ae8a56b8ed13e5a8c8a61194b3c236920999ab83/fastapi-0.136.3-py3-none-any.whl", hash = "sha256:3d2a69bdf04b7e9f3afa292c3bc7a98816bbfafa10bc9b45f3f3700d2f761620", size = 117481, upload-time = "2026-05-23T18:53:16.924Z" },
 ]

 [[package]]
 name = "fastapi-toolsets"
-version = "4.1.1"
+version = "5.0.0b1"
 source = { editable = "." }
 dependencies = [
    { name = "asyncpg" },
@@ -1165,27 +1165,27 @@ wheels = [

 [[package]]
 name = "ruff"
-version = "0.15.14"
+version = "0.15.15"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/dc/8a/8bce2894573e9dae6ff4d77fe34ad727d79b9e6238ad288c5638990d90f6/ruff-0.15.14.tar.gz", hash = "sha256:48e866b165be4a9bdbf310f7d3c9a07edef2fe8cd63ffeb4e00bb590506ebf9f", size = 4700910, upload-time = "2026-05-21T14:34:55.177Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/84/6f/a76f7d96e5c962f5b69cee865e49c15c1116897c01990faa8a57edb62e7f/ruff-0.15.15.tar.gz", hash = "sha256:b8dff018130b46d8e5bf0f926ef6b60cf871d6d5ae45fc9334e09632daa741d6", size = 4706985, upload-time = "2026-05-28T14:16:57.784Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b9/c8/74a92c6ff9fcfb4f1f947126d3ebee8389276e161ecc85de5bda7cda51bd/ruff-0.15.14-py3-none-linux_armv6l.whl", hash = "sha256:8dd2db9416e487c8d4b01fa7056bb02c4d05969d4f8d17a08c229c2f4ff3c108", size = 10739177, upload-time = "2026-05-21T14:34:37.332Z" },
-    { url = "https://files.pythonhosted.org/packages/45/91/254a35c20acc38a7223c9d2d594af12e794432464f2cdeb52af1dc4a892d/ruff-0.15.14-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:be4ff55af755bd71a00ab3dc6bd7ffc467bd76e0df6881e286c2e3d23e8fb43b", size = 11144969, upload-time = "2026-05-21T14:34:43.978Z" },
-    { url = "https://files.pythonhosted.org/packages/56/9e/d13e40f83b8d0a94430e6778ce1d94a43b38cf2efe63278bdd2b4c65abbf/ruff-0.15.14-py3-none-macosx_11_0_arm64.whl", hash = "sha256:48d5909d7d06276ce7dde6d32bfa4b0d4cb2651145cd8ee4b440722cbc77832f", size = 10478207, upload-time = "2026-05-21T14:34:48.378Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/f1/b15a7839fa4f332f8acec78e20564f26bb2d866e3d21710b877fd0263000/ruff-0.15.14-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ca8cbfa94c4f90984a67561978602746d4cd27103568f745fa90eee3f0d4107d", size = 10818459, upload-time = "2026-05-21T14:34:22.318Z" },
-    { url = "https://files.pythonhosted.org/packages/45/33/53d651177f84f94b400a0e27f8824eeada3dddc9d5ee8aeb048f4352a520/ruff-0.15.14-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9a6bbc0333f1ab053423bcbf6226477d266ca7cec7738c4c8e3f55647803f3c4", size = 10541800, upload-time = "2026-05-21T14:34:20.209Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/a6/868f87e0bf9786ed24b5d0d0ad8676b8a94fd1912f42cddf9cfc7857818a/ruff-0.15.14-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:8a24a4f7605d7003a6674d4387651effd939dead3fddd0f36561eb77a9a2e542", size = 11342149, upload-time = "2026-05-21T14:34:46.365Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/8b/38cd5c19faffdcc05a408d2b78edccc69492ab9720eadb49ea15ef80d768/ruff-0.15.14-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:049b5326e53ed80978f2fc041a280603f69dd6b0c95464342a2bb4572d9d9e2f", size = 12212563, upload-time = "2026-05-21T14:34:28.579Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/4d/a3c5b874a556d5731e3e657aaf04311bb76f0a5c3ec220ed43051be6b64b/ruff-0.15.14-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d4ed42e6696c8dfa5f06728e6441993901f548eb92d73bc472cb5a38d1395fbf", size = 11493299, upload-time = "2026-05-21T14:34:41.836Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/c0/56472c251d09858a53e51efbd485b09e1995d8731668b76d52e5dd6ee0f1/ruff-0.15.14-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:715c543cf450c4888251f91c52f1942a800541d9bddd7ac060aa4e6b77ae7cba", size = 11455931, upload-time = "2026-05-21T14:34:57.276Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/4a/e2e7b4d8dbf233d4eace59c75bc3435fa6d8bd3bae82d351d4e4300c0fd1/ruff-0.15.14-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:72ebab6013ec887d439d8b7593737a0a4ffb06d45d209d4e4bf2e92813082d3f", size = 11400794, upload-time = "2026-05-21T14:34:39.773Z" },
-    { url = "https://files.pythonhosted.org/packages/97/c7/83c0539fe34c3e09136204d1e75d6052492364e0b3cb05e9465423f567d7/ruff-0.15.14-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:49072d36abdbe97a8dd7f480afe9c675699c0c495d4c84076e2c1203c4550581", size = 10804759, upload-time = "2026-05-21T14:34:31.045Z" },
-    { url = "https://files.pythonhosted.org/packages/86/a6/18f2bfc095a2ab4a78745644e428205532ce6653a5d0fa8501572891534d/ruff-0.15.14-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:958522aee105068640c2c2ceae08f413ae44d922f52a1374ac13d6a96032fc93", size = 10539517, upload-time = "2026-05-21T14:34:53.064Z" },
-    { url = "https://files.pythonhosted.org/packages/54/3a/5a8b3b69c654d4e4bf1d246ac5b49cbcdac6eaab6905925f8915f31e3b80/ruff-0.15.14-py3-none-musllinux_1_2_i686.whl", hash = "sha256:f3707da619a143a2e8830e2abab8224478d69ace2d28cb6c20543ae97c36bf61", size = 11065169, upload-time = "2026-05-21T14:34:24.484Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/c5/8864e4e7925b836ea354b31d57641ec03830564e281a8b6f061f8c3e0ec1/ruff-0.15.14-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:bb01d645694e3ec0102105d07ef2d53703970407d59c04e59d3ba0b7a1d53553", size = 11560214, upload-time = "2026-05-21T14:34:50.975Z" },
-    { url = "https://files.pythonhosted.org/packages/36/38/012bf76752e1f89ed50b77b99532d90f3a3e287bc7918e1fc0948ac866ac/ruff-0.15.14-py3-none-win32.whl", hash = "sha256:6d0c1ad2a0ab718d39b6d8fd2217981ce4d625cd96a720095f798fb47d8b13e6", size = 10805548, upload-time = "2026-05-21T14:34:33.453Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/b7/4ea2c170f10ad760fff2a5250beb18897719dc8b52b53a24cddbb9dd3f19/ruff-0.15.14-py3-none-win_amd64.whl", hash = "sha256:802342981e056db3851a7836e5b070f8f15f67d4a685ae2a6160939d364b2902", size = 11939523, upload-time = "2026-05-21T14:34:18.077Z" },
-    { url = "https://files.pythonhosted.org/packages/62/d5/bc97ff895ec35cf3925d4bd60f3b39d822f377a446906ec9bcc87405e59b/ruff-0.15.14-py3-none-win_arm64.whl", hash = "sha256:ff47b90a9ef6a40c9e2f3b479c1fb78531adf055b94c1eba0a7ba04b31951826", size = 11208607, upload-time = "2026-05-21T14:34:26.525Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/9d/3a45c05b8ab04b4705989de70a79008e27c8003296a0feaee9edc18dd7e9/ruff-0.15.15-py3-none-linux_armv6l.whl", hash = "sha256:cf93e5388f412e1b108b1f8b34a6e036b70fe8aff89393befad96fe48670311b", size = 10710652, upload-time = "2026-05-28T14:16:06.701Z" },
+    { url = "https://files.pythonhosted.org/packages/05/66/da974431624bf3b49f6ee1f9543c02d929ff1cba78b0d5a79c38cf21f744/ruff-0.15.15-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ac5a646d1f6a7dadd5d50842dae2c1f9862ac887ef5d1b1375e02def791fde6e", size = 11096615, upload-time = "2026-05-28T14:16:23.313Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/09/7443452e5d290230a712103f2fdceeef7184f3ec99a2bd01c8be78aaceb5/ruff-0.15.15-py3-none-macosx_11_0_arm64.whl", hash = "sha256:77d955a431430c66f72dd94e379ad38a16daea3d25094872ac4edf9e797be530", size = 10436683, upload-time = "2026-05-28T14:16:40.974Z" },
+    { url = "https://files.pythonhosted.org/packages/53/01/d330c26a57fa4f3943a14424904027428315b700fe4d14a84bb123a649e5/ruff-0.15.15-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7614ee79c69788cf6cedd568069ade9cecc22a1ad20494efe8d0c9ebb4b622d4", size = 10769064, upload-time = "2026-05-28T14:16:28.905Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/85/cc8770f8bdff541b1da8392d1634141fe4a0e3f4ee596605959b7906c27f/ruff-0.15.15-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3cdb1679e06a1f6b47bc384714ae96f6e2fb65ca441eb78c43d2ca554176ce1f", size = 10511987, upload-time = "2026-05-28T14:16:43.732Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/29/8c190c1472b63013583ba391f3342036e02010544c1270455ed8e519bdf3/ruff-0.15.15-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2728b93d7b23a603ea2c0ac6eb73d760bd38ec9de35f35fb41e18f7a3fee7622", size = 11275100, upload-time = "2026-05-28T14:16:55.244Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/6b/7e145ce2cc8e63d6834eca03d83a0e18d121def5c69f91b4cf4011ed4879/ruff-0.15.15-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:be582fcc0db438902c7792b08d6ddf6c9b9e21addaa10092c2c741cfb09e5a45", size = 12176903, upload-time = "2026-05-28T14:16:14.368Z" },
+    { url = "https://files.pythonhosted.org/packages/80/a3/d5974637f68e451f7fadf015cf3101d1cd7d8ba5027cffe0b9e3826ebe6b/ruff-0.15.15-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7aa77465b8ecaf1a27bea098d696f7fed5e1eccbd10b321b682d6de586ae5627", size = 11404550, upload-time = "2026-05-28T14:16:20.138Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/1c/e6e5e568f22be4fb05d6244234aba384c06b451252453b821e1a529263cf/ruff-0.15.15-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:48decfa11d740de4889de623be1463308346312f2409a56e24aa280c86162dc4", size = 11382027, upload-time = "2026-05-28T14:16:46.615Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/01/170921b49fcd2e8858825593f91cf7146c3e40a5c3e6df763e4bb0484dde/ruff-0.15.15-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:a5015088452ca0081387063649ec67f06d3d1d6b8b936a1f836b5e9657ecd48c", size = 11366041, upload-time = "2026-05-28T14:16:26.247Z" },
+    { url = "https://files.pythonhosted.org/packages/87/54/a7bad711d7de93254e15e06a4c375b89a03d18de45d3e5dcc86a4472fb1a/ruff-0.15.15-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:f5294aab6356c81600fcdea3a62bb1b924dfd5e91767c12318d3f68f86af57cd", size = 10741795, upload-time = "2026-05-28T14:16:17.11Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/31/38c075963668f8b41c6914ee0f6f318727fbe30ab9145cb29e6df464c5fa/ruff-0.15.15-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:db5bd4d802415cca656dc1616070b725952d6ae95eb5d4831e49fbd94a38f75f", size = 10511117, upload-time = "2026-05-28T14:16:31.767Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/96/6ff689e1f7e375d1d97075eca022f74c2bab59554a432fe4d2e6f091986a/ruff-0.15.15-py3-none-musllinux_1_2_i686.whl", hash = "sha256:587a6278ed42059191c1a466e490bd7930fb50bd2e255398bc29616c895a61cb", size = 10994867, upload-time = "2026-05-28T14:16:35.149Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/c2/5dce0ab9f92a8d534fa62b9bf9caca3eddb8c1a81b616f5e195ada4f0d6e/ruff-0.15.15-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:df0c1c084f5f4be9812f61518a45c440d3c30d69ce4bf6c5270e66d38338f02a", size = 11482101, upload-time = "2026-05-28T14:16:49.598Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/c0/1003b60edd697c649faf61f1a34094b1abb38fb3d1181e3f895781250a08/ruff-0.15.15-py3-none-win32.whl", hash = "sha256:29428ea79694afbe756d45fd59b36f22b6b020dc0443cf7de0173046236964b9", size = 10716774, upload-time = "2026-05-28T14:16:52.337Z" },
+    { url = "https://files.pythonhosted.org/packages/02/a8/1269eddd6945a06c23f055ef7848886e37cf9d6a8bebb386a3115f01470c/ruff-0.15.15-py3-none-win_amd64.whl", hash = "sha256:8df0323902e15e24bc4bf246da830573d3cf3352bd0b9a164eab335d111ff4a4", size = 11868463, upload-time = "2026-05-28T14:16:11.333Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/b2/920464c907b191e37469d477a1aa8bc048b8f36c4c1610dfa4ab87b39e18/ruff-0.15.15-py3-none-win_arm64.whl", hash = "sha256:3c8ceca6792f38196b8f589bc92eccd03eef286602da92e5dc05cc42ef6441b7", size = 11138498, upload-time = "2026-05-28T14:16:38.425Z" },
 ]

 [[package]]
@@ -1262,15 +1262,15 @@ asyncio = [

 [[package]]
 name = "starlette"
-version = "0.50.0"
+version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "anyio" },
    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/ba/b8/73a0e6a6e079a9d9cfa64113d771e421640b6f679a52eeb9b32f72d871a1/starlette-0.50.0.tar.gz", hash = "sha256:a2a17b22203254bcbc2e1f926d2d55f3f9497f769416b3190768befe598fa3ca", size = 2646985, upload-time = "2025-11-01T15:25:27.516Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d9/52/1064f510b141bd54025f9b55105e26d1fa970b9be67ad766380a3c9b74b0/starlette-0.50.0-py3-none-any.whl", hash = "sha256:9e5391843ec9b6e472eed1365a78c8098cfceb7a74bfd4d6b1c0c0095efb3bca", size = 74033, upload-time = "2025-11-01T15:25:25.461Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" },
 ]

 [[package]]
@@ -1329,32 +1329,32 @@ wheels = [

 [[package]]
 name = "ty"
-version = "0.0.38"
+version = "0.0.44"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/33/3b/45be6b37d5060d6917bf7f1f234c00d360fc5f8b7486f8a96af640e25661/ty-0.0.38.tar.gz", hash = "sha256:fbc8d47f7630457669ab41e333dc093897fdb7ead1ffc94dcf8f30b5d39aa56d", size = 5681218, upload-time = "2026-05-20T00:15:32.781Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/13/f4/fbb120226e4f239652525a664bad976a23fea58c646d1323f2296fee8a61/ty-0.0.44.tar.gz", hash = "sha256:5886229830ab77022842a1c55d2ef57405621a91fc465969fa6d538661898173", size = 5803665, upload-time = "2026-06-05T03:33:48.612Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/54/43/ea9b4e57d6a266670dbe34858e92f6093ca054ad1b48f1c82580a72340fb/ty-0.0.38-py3-none-linux_armv6l.whl", hash = "sha256:3501dcf44ca03f813f9cb4fabfdf601adc0ac1337c411405b470530679e37a45", size = 11289326, upload-time = "2026-05-20T00:14:52.371Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/ff/24e2f623a1c6b5f5ccf8bf82fccd937033c6a7dba57a4028c7f41270fa4a/ty-0.0.38-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b34b4094b76252c3e8c90762cdd5e8a9f1101534484745ff4b480f71eb38ac2e", size = 11063047, upload-time = "2026-05-20T00:14:42.832Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/41/4f0d910f0acbd20b358eda80a5cd6a8361d27ff5b8e87ab559d3f69f125e/ty-0.0.38-py3-none-macosx_11_0_arm64.whl", hash = "sha256:c518ad33a877677365baab2e21d82cf59ffee789203a15a143f5179ee5a1d3f8", size = 10494436, upload-time = "2026-05-20T00:15:24.425Z" },
-    { url = "https://files.pythonhosted.org/packages/69/d8/da06833422082aa98b169a391f9197e2d73865e96c90b6979ac886b890a2/ty-0.0.38-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9238494722303eccddc6a27eb647948b694eecd6b974910d13b9e6cd46bbeb6a", size = 11000992, upload-time = "2026-05-20T00:14:58.368Z" },
-    { url = "https://files.pythonhosted.org/packages/16/f7/e1172197fb827e6410ca3eb0dc68ef2789f3c70683696f2a0ce5c90764fd/ty-0.0.38-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:31d91d7336c5d51bf822ac0df512f300584ca4dcca041fc6a6d7df03a8ddbb31", size = 11058583, upload-time = "2026-05-20T00:15:11.314Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/61/7fbaf0c05981e006a8804287819c574dff90a6bf8e96efad7226be0700aa/ty-0.0.38-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:65165879814993450710b9349791e4898c65e36b1e14eec554884c06a2f20ff1", size = 11531036, upload-time = "2026-05-20T00:15:14.62Z" },
-    { url = "https://files.pythonhosted.org/packages/49/e3/47c0c64e401d50f925df3e52479d4e7626754b2a9e38201d142fdacd6252/ty-0.0.38-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6d61868b8d1c4033bf8088191de953fed245c2f9e1bb9d2d53e5699170b0924c", size = 12129991, upload-time = "2026-05-20T00:14:39.475Z" },
-    { url = "https://files.pythonhosted.org/packages/90/99/2f452d02901bcd7f1b109cf5b848727ce37f372c3406143aa52d1305d40e/ty-0.0.38-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8f9a9175548c98dbff7707865738c07c2b1f8e07a09b8c68101baebb5dac59a4", size = 11756167, upload-time = "2026-05-20T00:15:27.526Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/0c/c7e14d111c813e1a20b82e944f1c997c4631a2bb710eaa64fb6b26835e13/ty-0.0.38-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:375d3a964c6b4aea2e9237fdb5eb9ed03dc43088986a94209a28a4ea3b62001c", size = 11637099, upload-time = "2026-05-20T00:15:21.261Z" },
-    { url = "https://files.pythonhosted.org/packages/37/de/ab02659dd1ed62898db7db4d37f9937c80854dd45e95093fa0fe10328d82/ty-0.0.38-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:cdfd547782c45267aa0b52abad31bd406bf4768c264532ef9e2360cd3c6ce048", size = 11813583, upload-time = "2026-05-20T00:14:45.875Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/57/bd1b5ebf4e71a4295484afac0202df1740b0807762b86744b1bef4534984/ty-0.0.38-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:858bc675b75626470abe4e6c3b3934b853642b04f2ac4d7139fcefea3b48b213", size = 10975405, upload-time = "2026-05-20T00:15:30.354Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/55/0305c78711bbd23922cf291996a08ef9544f4179da98e9a75c14e608f379/ty-0.0.38-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:54be4f00432870da42cd74fe145a3362fd248e22d032c74bd807cb45bf068f94", size = 11097551, upload-time = "2026-05-20T00:14:55.179Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/4f/7effe7f9a6ac9719eb7234172c01739c5f888bb47f9acc2ea8da1f4afed3/ty-0.0.38-py3-none-musllinux_1_2_i686.whl", hash = "sha256:494af66a76a86dbf16a3003d3b63b03484aa4c7489dfe11f3ee5413b98b22d60", size = 11214391, upload-time = "2026-05-20T00:15:18.094Z" },
-    { url = "https://files.pythonhosted.org/packages/75/cd/d9fdfec3a74a6ad0209fa5e7113ae29d4f457d0651cfbb813b4c6563e0d4/ty-0.0.38-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:3d92527c4be78a5ce6d32e8bb0aa2a6988d4076eddf1294e56fdaf06d1a98e7e", size = 11730871, upload-time = "2026-05-20T00:14:49.219Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/4a/beefade12d109b4f7793d61b04b4478b1ad4d1465a719e7ff55b2d42461a/ty-0.0.38-py3-none-win32.whl", hash = "sha256:36fc5dd5dc09207ff3004b1560a79a3fb8d12456daeec914a7b802a918da654c", size = 10548583, upload-time = "2026-05-20T00:15:07.892Z" },
-    { url = "https://files.pythonhosted.org/packages/15/64/941b205e2e46cc2297c245c64aa7691410b7454fa4d07a6cb3cf59487833/ty-0.0.38-py3-none-win_amd64.whl", hash = "sha256:eef0a8956ba14514076b1a963d13eb32986d9ebad7f0527b3cc01cb68bf35147", size = 11650542, upload-time = "2026-05-20T00:15:01.441Z" },
-    { url = "https://files.pythonhosted.org/packages/59/02/c1c4f9ec4b94d95190636fa13f79c32f65165fbe3a0503882d4df164d2ac/ty-0.0.38-py3-none-win_arm64.whl", hash = "sha256:79abfc8658a026c30b1c955613437dab3ef4b12feca56a3e6df50903cc39e07f", size = 11010307, upload-time = "2026-05-20T00:15:04.567Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/c6/b5b8c4762efb4d85401652658786506867553ecfc2beac3bcf361a15937f/ty-0.0.44-py3-none-linux_armv6l.whl", hash = "sha256:272d31e7ad49b1dc5e8465a9fe700354e14c755b40d9c75f08f031d786903df3", size = 11607267, upload-time = "2026-06-05T03:33:27.154Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/5c/f4b405570737f44ab0fc4214117fe43353f8f0825a1823d9e99e9c8e57be/ty-0.0.44-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b92c4ddd7a3daf2049715edec9dc70cf6fd31a5a318ee647258f90dd75495eed", size = 11382826, upload-time = "2026-06-05T03:33:54.374Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/aa/fb9835aa492b148d7754cb4c3db07f31a7e2e09f0d8e0e8e297f01125dd2/ty-0.0.44-py3-none-macosx_11_0_arm64.whl", hash = "sha256:4d42cfd84a690f6654b2a4f0515027c21b692cf2512d32e6433f754893a95609", size = 10809741, upload-time = "2026-06-05T03:33:33.22Z" },
+    { url = "https://files.pythonhosted.org/packages/47/f5/0b20ba6b66837a5a37bab7f74ac0732c66e766b5f0b2d55b30816b15f348/ty-0.0.44-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5dc47ae87e4cb7db2a9166bb23b78a905c3626e523296ec5bccf36b5e89bda6b", size = 11318153, upload-time = "2026-06-05T03:34:09.403Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/bb/b82ea730774a4f950f06d355fbc120d51eac7da23b57fc79ef6ff7c79cbb/ty-0.0.44-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:46d867e80f16f421ac72c9a85240dbf050d62d9b3fbd10a8b5b082fb21679e0b", size = 11403108, upload-time = "2026-06-05T03:33:57.745Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/41/e2c83856165291049c702eda4e2ef3d3ebd875e8a0a77b8cc4ef3156aa1c/ty-0.0.44-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:411f5de0f96a4e4e5cccc3e0d55954c41f6a99ee6ca1fe5a7226cbc68406e053", size = 11944815, upload-time = "2026-06-05T03:34:15.793Z" },
+    { url = "https://files.pythonhosted.org/packages/66/95/1fa6a101eb9d5bec042b87e5ca9c8fc349b75961beca6306f95af5cd5539/ty-0.0.44-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4b15f01ecb4e2b46c05a1769293f9d32c3d4a1e4e7dfccf37c604d705dc3e3f4", size = 12476121, upload-time = "2026-06-05T03:33:51.529Z" },
+    { url = "https://files.pythonhosted.org/packages/72/6a/da4b45b1229d39207c6140681c2aaf4f5691bcb1dc830b84450ca25c8f57/ty-0.0.44-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:edd32b7467af509c99c0244c2226a4e4c03400699003ec33373282ab931654d9", size = 12091340, upload-time = "2026-06-05T03:33:36.289Z" },
+    { url = "https://files.pythonhosted.org/packages/16/c7/e1c9260ea5188195962ff1214ace418b5d69187e8fa7c0a1ec4994b8071b/ty-0.0.44-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:503a585f4007387c3afc58bae23a7ca1b9f236cbdb1a881dc36110655ceb1937", size = 11986201, upload-time = "2026-06-05T03:34:00.624Z" },
+    { url = "https://files.pythonhosted.org/packages/92/f9/312bb112da9b1a7da295bb0426be85e72ad48da4e4266c36d77256b4058d/ty-0.0.44-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:2d28bcfa83243d77c2316944e8cf197f73597bf17d1ddc047d0b10a762531252", size = 12168475, upload-time = "2026-06-05T03:33:30.386Z" },
+    { url = "https://files.pythonhosted.org/packages/02/de/64978d603f6c3e5dd7cb97eca2214567d8ad0c85fa4a7435b7852ae4b779/ty-0.0.44-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:56fd2dd0192def189715b25f5338f6222fb827884dc34111e50aa1c4e061cee5", size = 11292937, upload-time = "2026-06-05T03:34:06.448Z" },
+    { url = "https://files.pythonhosted.org/packages/64/63/a625d8a3c71dcaa01988d330f849c465fe72ead4b0bbab44fe4bd6e672b5/ty-0.0.44-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:7f8d990489032de1984e73c159f3e760d754cf83a602b874827d943821f63595", size = 11421560, upload-time = "2026-06-05T03:33:23.995Z" },
+    { url = "https://files.pythonhosted.org/packages/99/96/61aeba0e629b0c91bd316ff94d00e38817ec493ae4316f39508988daa287/ty-0.0.44-py3-none-musllinux_1_2_i686.whl", hash = "sha256:f61ffe72996a755432922fe90b28db593f572eb5cbf48e3ef4e67b282533d1b0", size = 11580282, upload-time = "2026-06-05T03:34:03.308Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/f7/256e1538ce21cab67b381201444c42454de69d310059c4929d92a0ee9c48/ty-0.0.44-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:2b237a143bac4f30cec9257d45f01e72da97030a80a09a2b69cfef065f09c37f", size = 12085723, upload-time = "2026-06-05T03:33:45.953Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/76/ec3957c10872643a98db7a7895101ad89c5b7cba4bc6c4aebbbfc91756cc/ty-0.0.44-py3-none-win32.whl", hash = "sha256:6a24586c65419223ac5bab4822d49ab493a5d19ea2a897514284c232b9d6166a", size = 10892978, upload-time = "2026-06-05T03:34:12.603Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/7d/ba24050432196e7d7f03945e5c379951593c48e04e5c5d5275cfc4624791/ty-0.0.44-py3-none-win_amd64.whl", hash = "sha256:8cccb27e348c89a9733fbad1b2efadfbad79b107c7e52adb52dfd8a70156a38d", size = 11987058, upload-time = "2026-06-05T03:33:42.692Z" },
+    { url = "https://files.pythonhosted.org/packages/71/34/16ec3f1fec75292d9c56a8b5fef037ceaba85a5c30562206c1a245a00a67/ty-0.0.44-py3-none-win_arm64.whl", hash = "sha256:58049504e7a12bf1957f24a5384a332c94d5590127083a80db5e5a1bed34190b", size = 11329961, upload-time = "2026-06-05T03:33:39.427Z" },
 ]

 [[package]]
 name = "typer"
-version = "0.26.2"
+version = "0.26.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "annotated-doc" },
@@ -1362,9 +1362,9 @@ dependencies = [
    { name = "rich" },
    { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/67/a5/756f2e6bc81a7dd79aa3c625dd01b74cabc4516628cace2caaec09ca6ff2/typer-0.26.2.tar.gz", hash = "sha256:9b4f19e08fcc9427a822d1ef467b1fe76737a2f65c7926bdeba2337d73569b68", size = 198991, upload-time = "2026-05-27T10:41:39.166Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5e/ed/ef06584ccdd5c410df0837951ecd7e15d9a6144ea1bd4c73cecab1a89891/typer-0.26.7.tar.gz", hash = "sha256:e314a34c617e419c091b2830dda3ea1f257134ff593061a8f5b9717ab8dddb3a", size = 201709, upload-time = "2026-06-03T07:18:06.843Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/8b/a5/6ffd702beda8798b2b82ff70805ed4a66d963557e43a5d1823ab456251a4/typer-0.26.2-py3-none-any.whl", hash = "sha256:39beff72ffbb31978a5b545f677d57edb97c6f980f433b38556deb0af25f094d", size = 123123, upload-time = "2026-05-27T10:41:40.504Z" },
+    { url = "https://files.pythonhosted.org/packages/24/25/2201973529af2c954de0bb725323c3aaed6d7f0ceee8f550dec9185df013/typer-0.26.7-py3-none-any.whl", hash = "sha256:5c87cfbc5d34491c5346ebf49c23e18d56ccb863268d3a8d592b26087c2f5e58", size = 122456, upload-time = "2026-06-03T07:18:05.732Z" },
 ]

 [[package]]
Author	SHA1	Message	Date
d3vyce	025f1907fd	Version 5.0.0-beta1	2026-06-25 15:15:49 -04:00
d3vyceandGitHub	9698a0743b	chore: rework DB module (#324 )	2026-06-25 21:11:50 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	22f307d0fc	⬆ Bump starlette from 1.0.1 to 1.3.1 (#315 ) Bumps [starlette](https://github.com/Kludex/starlette) from 1.0.1 to 1.3.1. - [Release notes](https://github.com/Kludex/starlette/releases) - [Changelog](https://github.com/Kludex/starlette/blob/main/docs/release-notes.md) - [Commits](https://github.com/Kludex/starlette/compare/1.0.1...1.3.1) --- updated-dependencies: - dependency-name: starlette dependency-version: 1.3.1 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-06-20 15:27:11 +02:00
d3vyce	2641881df5	Version 4.1.3	2026-06-09 12:48:01 -04:00
d3vyceandGitHub	49b579bcec	feat: add optional prefix parameter to create_worker_database and worker_database_url (#306 )	2026-06-09 18:46:09 +02:00
d3vyceandGitHub	4bb4287922	fix: drop worker database with force to handle active connections (#304 )	2026-06-09 18:34:44 +02:00
d3vyce	43445e931e	Version 4.1.2	2026-06-08 12:41:22 -04:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	27a36b0c82	⬆ Bump ty from 0.0.38 to 0.0.44 (#299 ) Bumps [ty](https://github.com/astral-sh/ty) from 0.0.38 to 0.0.44. - [Release notes](https://github.com/astral-sh/ty/releases) - [Changelog](https://github.com/astral-sh/ty/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ty/compare/0.0.38...0.0.44) --- updated-dependencies: - dependency-name: ty dependency-version: 0.0.43 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-06-08 18:40:30 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	d81adde685	⬆ Bump typer from 0.26.2 to 0.26.7 (#298 ) Bumps [typer](https://github.com/fastapi/typer) from 0.26.2 to 0.26.7. - [Release notes](https://github.com/fastapi/typer/releases) - [Changelog](https://github.com/fastapi/typer/blob/master/docs/release-notes.md) - [Commits](https://github.com/fastapi/typer/compare/0.26.2...0.26.7) --- updated-dependencies: - dependency-name: typer dependency-version: 0.26.7 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-06-08 18:40:22 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	c96779f10c	⬆ Bump ruff from 0.15.14 to 0.15.15 (#297 ) Bumps [ruff](https://github.com/astral-sh/ruff) from 0.15.14 to 0.15.15. - [Release notes](https://github.com/astral-sh/ruff/releases) - [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md) - [Commits](https://github.com/astral-sh/ruff/compare/0.15.14...0.15.15) --- updated-dependencies: - dependency-name: ruff dependency-version: 0.15.15 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-06-08 18:40:13 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	880009dd9a	⬆ Bump fastapi from 0.136.1 to 0.136.3 (#296 ) Bumps [fastapi](https://github.com/fastapi/fastapi) from 0.136.1 to 0.136.3. - [Release notes](https://github.com/fastapi/fastapi/releases) - [Commits](https://github.com/fastapi/fastapi/compare/0.136.1...0.136.3) --- updated-dependencies: - dependency-name: fastapi dependency-version: 0.136.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-06-08 18:40:02 +02:00
d3vyceandGitHub	3e2518b803	fix/create_worker_database connects to non-existent database on fresh setup (#302 ) * fix/create_worker_database connects to non-existent database on fresh setup * tests: add more tests for pytest module	2026-06-08 18:37:59 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	98328d4e20	⬆ Bump starlette from 0.50.0 to 1.0.1 (#300 ) Bumps [starlette](https://github.com/Kludex/starlette) from 0.50.0 to 1.0.1. - [Release notes](https://github.com/Kludex/starlette/releases) - [Changelog](https://github.com/Kludex/starlette/blob/main/docs/release-notes.md) - [Commits](https://github.com/Kludex/starlette/compare/0.50.0...1.0.1) --- updated-dependencies: - dependency-name: starlette dependency-version: 1.0.1 dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-06-06 15:37:36 +02:00