mgf-sqlalchemy 0.1.0__tar.gz

mgf_sqlalchemy-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing and coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pyre/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# Packaging
+MANIFEST
+
+# Claude Code — keep settings.json (committed for the team), ignore
+# per-machine local overrides + runtime locks/state.
+.claude/settings.local.json
+.claude/*.lock
+.claude/scheduled_tasks*
+
+# Maintainer planning notes (per-machine; never commit)
+my_stuff/

mgf_sqlalchemy-0.1.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to `mgf-sqlalchemy` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+the project follows [SemVer](https://semver.org/spec/v2.0.0.html). Per
+the 0.x window ([SemVer 0.x](https://semver.org/#spec-item-4) and rule
+**AP-03** from `mgf-common/docs/standards/API_DESIGN.md`), MINOR
+releases MAY break the public API. Pin tightly:
+
+```toml
+mgf-sqlalchemy = ">=0.X.0,<0.Y"   # one minor at a time
+```
+
+The release-engineering discipline that produces this changelog is in
+[`mgf-common/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/RELEASING.md).
+
+---
+
+## [Unreleased]
+
+Nothing yet.
+
+---
+
+## [0.1.0] — 2026-05-10
+
+PyPI: <https://pypi.org/project/mgf-sqlalchemy/0.1.0/> · Tag: `v0.1.0`
+
+> **Maiden voyage** — extracted from `mgf-common` v0.29.0 per the
+> federation split plan ([mgf-common/docs/release/federation_roadmap.md](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/release/federation_roadmap.md)).
+> Cutover guide: [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md).
+
+### Added
+
+- **`mgf.sqlalchemy.create_engine`** — async SQLAlchemy engine
+  factory wrapping `sqlalchemy.ext.asyncio.create_async_engine` with
+  production-leaning defaults: `pool_pre_ping=True` (catches stale
+  connections after DB restart), `pool_recycle=3600` (avoids MySQL
+  `wait_timeout` surprise), conservative `pool_size`/`max_overflow`.
+  SQLite-aware: detects `sqlite://` / `sqlite+` URLs and omits pool
+  kwargs that `StaticPool` / `NullPool` reject. `**extra` forwarded
+  to `create_async_engine` for rare options.
+- **`mgf.sqlalchemy.create_sessionmaker`** — async sessionmaker
+  factory wrapping `async_sessionmaker` with SQLAlchemy 2's
+  recommended `expire_on_commit=False` default for async sessions.
+  `expire_on_commit=True` opts back into the legacy synchronous
+  semantics.
+- **`mgf.sqlalchemy.tenant_session`** — async context manager that
+  runs `SET LOCAL app.current_tenant = '<uuid>'` for Postgres
+  RLS-based multi-tenancy. The `LOCAL` qualifier scopes to the
+  current transaction (auto-resets on commit/rollback) so
+  cross-tenant leakage between requests is impossible at the SQL
+  layer. `tenant_id` is UUID-validated before interpolation
+  (Postgres `SET LOCAL` doesn't accept bind params, so literal
+  interpolation is the only path; UUID validation makes it safe).
+
+### Removed (BREAKING vs the pre-extraction `mgf.common.db` shape)
+
+- **`get_session` and `setup_db`** are NOT in this sibling. They
+  were FastAPI-Depends and FastAPI-lifespan shaped respectively in
+  mgf-common — pulling Starlette/FastAPI into a "framework-agnostic
+  SQLAlchemy" sibling would violate the closed-box rule. They moved
+  to `mgf.fastapi.db.get_session` / `mgf.fastapi.db.setup_db` in
+  mgf-fastapi v0.2.0 (gated behind the `mgf-fastapi[sqlalchemy]`
+  optional extra). Consumers needing them install both
+  `mgf-sqlalchemy` and `mgf-fastapi[sqlalchemy]`.
+
+### Engineering
+
+- 11 tests carried over from `mgf-common/tests/unit/db/test_engine.py`
+  + the non-FastAPI portions of `test_session.py` — every
+  pre-extraction failure mode for the helpers in this sibling stays
+  green at parity. Coverage threshold ≥80% (matches mgf-common's
+  standard).
+- Imports rewrite from `mgf.common.db.*` to `mgf.sqlalchemy.*`. No
+  private-import leaks; the sibling reaches into mgf-common only
+  through public names.
+- `mgf-common>=0.30,<0.31` runtime dependency. AP-03 0.x window pin
+  discipline applies — bump in lock-step with mgf-common's next
+  minor.
+- PEP 420 namespace package (no top-level `mgf/__init__.py`); the
+  wheel ships `src/mgf/` as-is so `mgf.sqlalchemy`, `mgf.alembic`,
+  `mgf.fastapi`, `mgf.http`, and `mgf.common` coexist as siblings.

mgf_sqlalchemy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bassam Alsanie and mgf-common contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mgf_sqlalchemy-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: mgf-sqlalchemy
+Version: 0.1.0
+Summary: Async SQLAlchemy helpers for mgf-common consumers — typed engine factory, sessionmaker, Postgres RLS tenant-scoping. Sibling of mgf-common under the mgf.* namespace.
+Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-sqlalchemy
+Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-sqlalchemy/issues
+Project-URL: Changelog, https://codeberg.org/magogi-admin/mgf-sqlalchemy/src/branch/main/CHANGELOG.md
+Author: Bassam Alsanie, mgf-sqlalchemy contributors
+License: MIT
+License-File: LICENSE
+Keywords: async,asyncpg,engine,multi-tenant,rls,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mgf-common<0.31,>=0.30
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: aiosqlite>=0.20; extra == 'test'
+Description-Content-Type: text/markdown
+
+# `mgf-sqlalchemy` — async SQLAlchemy helpers for mgf-common consumers
+
+[![PyPI](https://img.shields.io/pypi/v/mgf-sqlalchemy)](https://pypi.org/project/mgf-sqlalchemy/)
+[![Python](https://img.shields.io/pypi/pyversions/mgf-sqlalchemy)](https://pypi.org/project/mgf-sqlalchemy/)
+
+> **Sibling of [`mgf-common`](https://pypi.org/project/mgf-common/)
+> under the `mgf.*` namespace.** Houses the async-SQLAlchemy helpers
+> that previously lived under `mgf.common.db.*` — extracted at
+> mgf-common v0.30 / mgf-sqlalchemy v0.1 per the
+> [federation split plan](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/release/federation_roadmap.md).
+
+## What this provides
+
+| Submodule | What |
+|---|---|
+| `mgf.sqlalchemy` | `create_engine` — async SQLAlchemy engine factory with production-leaning pool defaults (`pool_pre_ping`, `pool_recycle`, sane `pool_size`/`max_overflow`). SQLite-aware (skips pool kwargs that StaticPool/NullPool reject). `create_sessionmaker` — async sessionmaker factory with SQLAlchemy 2's recommended `expire_on_commit=False` default. `tenant_session` — context manager for Postgres RLS multi-tenancy (`SET LOCAL app.current_tenant = '<uuid>'`); UUID-validated to prevent SQL injection. |
+
+**FastAPI helpers live elsewhere.** The `get_session`
+FastAPI-Depends generator and the `setup_db` lifespan helper that
+previously co-located with these in mgf-common moved to
+[`mgf.fastapi.db`](https://pypi.org/project/mgf-fastapi/) in
+mgf-fastapi v0.2.0 (which depends on mgf-sqlalchemy via its
+`[sqlalchemy]` extra). This sibling stays framework-agnostic — no
+Starlette / no FastAPI in the dependency graph.
+
+## Install
+
+```bash
+pip install mgf-sqlalchemy
+# Or with the test extra (aiosqlite for in-memory SQLite tests):
+pip install 'mgf-sqlalchemy[test]'
+```
+
+Pulls in `mgf-common` + `sqlalchemy[asyncio]` automatically. Production
+consumers also need an async driver of their own (asyncpg / aiomysql /
+asyncmy); we don't pin one — the consumer picks based on their
+database.
+
+## Quick start
+
+```python
+import asyncio
+from mgf.sqlalchemy import create_engine, create_sessionmaker
+
+async def main() -> None:
+    engine = create_engine(
+        "postgresql+asyncpg://user:pass@localhost/myapp",
+        echo=False,
+    )
+    sessionmaker = create_sessionmaker(engine)
+    try:
+        async with sessionmaker() as session:
+            from sqlalchemy import text
+            row = (await session.execute(text("SELECT 1"))).scalar_one()
+            print(row)
+    finally:
+        await engine.dispose()
+
+asyncio.run(main())
+```
+
+## Postgres RLS multi-tenancy
+
+```python
+from uuid import UUID
+from mgf.sqlalchemy import tenant_session
+
+tenant_id = UUID("550e8400-e29b-41d4-a716-446655440000")
+
+async with sessionmaker() as session:
+    async with tenant_session(session, tenant_id) as scoped:
+        # Every query on `scoped` (same session, just tenant-scoped)
+        # gets `app.current_tenant` set in the current transaction.
+        # RLS policies in your schema can read from
+        # `current_setting('app.current_tenant')`.
+        rows = await scoped.execute(text("SELECT ..."))
+```
+
+## FastAPI integration
+
+The FastAPI-shaped helpers (request-scoped session injection +
+lifespan) live in mgf-fastapi:
+
+```python
+# pyproject.toml
+dependencies = [
+    "mgf-common>=0.30,<0.31",
+    "mgf-sqlalchemy>=0.1,<0.2",
+    "mgf-fastapi[sqlalchemy]>=0.2,<0.3",
+]
+```
+
+```python
+from typing import Annotated
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from mgf.fastapi.db import get_session, setup_db
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with setup_db(app, database_url="postgresql+asyncpg://..."):
+        yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/users")
+async def list_users(
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> list[dict]:
+    ...
+```
+
+## Documentation
+
+- [`docs/recipes/sqlalchemy.md`](docs/recipes/sqlalchemy.md) — full async-SQLAlchemy walkthrough.
+- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.30 split + the get_session/setup_db relocation to mgf-fastapi).
+- [`PUBLIC_API.md`](PUBLIC_API.md) — full public surface contract.
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+
+For the federation-wide engineering standards (DESIGN_PRINCIPLES,
+ERROR_HANDLING, SECURITY, etc.) see
+[`mgf-common/docs/standards/`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/).
+This sibling inherits them by reference; the standards
+source-of-truth lives in mgf-common.
+
+## Status
+
+🚧 **Experimental** — every public name is `experimental` per AP-09.
+Promotion to `stable` happens release-by-release as consumer feedback
+in [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/FEEDBACK.md)
+converges. The 0.x window applies. Pin tightly:
+`mgf-sqlalchemy = ">=0.X.0,<0.Y"`.
+
+## Cross-references
+
+- **Filing process for sharp edges**: open an entry on
+  [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/FEEDBACK.md)
+  with `[mgf-sqlalchemy]` prefix, OR file directly on this repo's
+  Issues → maintainer mirrors into the canonical FEEDBACK.md.
+- **Federation pattern**:
+  [`mgf-common/docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/design/federation.md).
+- **The split that created this sibling**:
+  [`mgf-common/docs/release/federation_roadmap.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/release/federation_roadmap.md).
+- **Companion sibling**: [`mgf-alembic`](https://pypi.org/project/mgf-alembic/) — async-aware alembic env.py helper (paired ship at v0.30; depends on this sibling).

mgf_sqlalchemy-0.1.0/PUBLIC_API.md

@@ -0,0 +1,81 @@
+# Public API — `mgf-sqlalchemy`
+
+> ⚠️ **This file documents `master` HEAD.** Names listed here may
+> be unreleased. To learn what your installed wheel actually
+> ships, run `pip show mgf-sqlalchemy` and compare against the git
+> tag matching the published version.
+
+This document is the **contract list** for `mgf-sqlalchemy`. Every
+name listed below is a public name that consumers MAY depend on.
+
+The contract terms are defined in
+[`mgf-common/docs/standards/API_DESIGN.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/API_DESIGN.md). In
+short:
+
+- **Stability tiers:**
+  - `experimental` — MAY change shape in any MINOR release
+    (the 0.x window keeps everything experimental in practice).
+  - `stable` — follows the deprecation cycle; removal only in MAJOR.
+  - `deprecated` — slated for removal; emits `DeprecationWarning`.
+- **Names not listed below are private.** Anything starting with
+  `_` (underscore-prefixed module names like `_engine.py`) is
+  internal and MAY change without notice.
+- **The 0.x window applies.** Per [SemVer](https://semver.org/) 0.x
+  semantics, MINOR releases MAY break the public API. Pin tightly:
+  `mgf-sqlalchemy = ">=0.X.0,<0.Y"`.
+
+---
+
+## `mgf.sqlalchemy`
+
+Top-level async SQLAlchemy helpers. Closed-box: depends on
+`mgf-common` + `sqlalchemy[asyncio]` only — **no FastAPI / Starlette /
+Django** in the runtime graph.
+
+| Name | Tier | Description |
+|---|---|---|
+| `create_engine` | experimental | Async SQLAlchemy engine factory. Wraps `sqlalchemy.ext.asyncio.create_async_engine` with production-leaning pool defaults (`pool_pre_ping=True`, `pool_recycle=3600`, conservative `pool_size`/`max_overflow`). SQLite-aware (skips pool kwargs that StaticPool/NullPool reject). `**extra` forwarded for rare options like `connect_args`, `isolation_level`. Returns an unconnected `AsyncEngine`. |
+| `create_sessionmaker` | experimental | Async sessionmaker factory. Wraps `async_sessionmaker` with SQLAlchemy 2's recommended `expire_on_commit=False` default. `expire_on_commit=True` opts back into the legacy synchronous semantics. |
+| `tenant_session` | experimental | Async context manager for Postgres RLS multi-tenancy. Runs `SET LOCAL app.current_tenant = '<uuid>'` on the supplied session; the `LOCAL` qualifier scopes the setting to the current transaction (auto-resets on commit/rollback). `tenant_id` accepts a `UUID` object or a UUID-shaped string; non-UUID input raises `ValueError` before any SQL is emitted. SQLite raises at the SQL layer (no GUC support); Postgres needs the GUC declared either in `postgresql.conf` or via a migration. |
+
+### Behaviours guaranteed at the public surface
+
+- `create_engine` accepts any SQLAlchemy URL and never connects
+  eagerly — the first connection attempt happens lazily on the
+  first `await engine.connect()` or sessionmaker call.
+- `tenant_session` validates `tenant_id` is UUID-shaped BEFORE
+  interpolating into the `SET LOCAL` SQL. Non-UUID input raises
+  `ValueError`; the SQL never runs.
+
+---
+
+## What stays in `mgf-common`, NOT here
+
+- **`AppError`, `OperationError`, `AppConfigError`** and the rest
+  of the typed exception hierarchy — `mgf.common.exceptions`.
+- **`bootstrap`, `app_name`, `app_version`, `current_context`** —
+  `mgf.common`.
+
+`mgf-sqlalchemy` reaches into none of mgf-common's private modules.
+The runtime dep is `mgf-common>=0.30,<0.31`.
+
+## What lives in `mgf-fastapi`, NOT here
+
+- **`get_session`** — FastAPI-Depends-compatible session generator.
+  Yields one `AsyncSession` per request from
+  `request.app.state.mgf_db_sessionmaker`. Lives in
+  `mgf.fastapi.db.get_session` (mgf-fastapi v0.2+).
+- **`setup_db`** — FastAPI lifespan context manager that creates
+  the engine + sessionmaker, stashes them on `app.state`, and
+  disposes the engine cleanly at lifespan exit. Lives in
+  `mgf.fastapi.db.setup_db` (mgf-fastapi v0.2+).
+
+Install both siblings to get the FastAPI-shaped helpers:
+
+```toml
+dependencies = [
+    "mgf-common>=0.30,<0.31",
+    "mgf-sqlalchemy>=0.1,<0.2",
+    "mgf-fastapi[sqlalchemy]>=0.2,<0.3",
+]
+```

mgf_sqlalchemy-0.1.0/README.md

@@ -0,0 +1,145 @@
+# `mgf-sqlalchemy` — async SQLAlchemy helpers for mgf-common consumers
+
+[![PyPI](https://img.shields.io/pypi/v/mgf-sqlalchemy)](https://pypi.org/project/mgf-sqlalchemy/)
+[![Python](https://img.shields.io/pypi/pyversions/mgf-sqlalchemy)](https://pypi.org/project/mgf-sqlalchemy/)
+
+> **Sibling of [`mgf-common`](https://pypi.org/project/mgf-common/)
+> under the `mgf.*` namespace.** Houses the async-SQLAlchemy helpers
+> that previously lived under `mgf.common.db.*` — extracted at
+> mgf-common v0.30 / mgf-sqlalchemy v0.1 per the
+> [federation split plan](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/release/federation_roadmap.md).
+
+## What this provides
+
+| Submodule | What |
+|---|---|
+| `mgf.sqlalchemy` | `create_engine` — async SQLAlchemy engine factory with production-leaning pool defaults (`pool_pre_ping`, `pool_recycle`, sane `pool_size`/`max_overflow`). SQLite-aware (skips pool kwargs that StaticPool/NullPool reject). `create_sessionmaker` — async sessionmaker factory with SQLAlchemy 2's recommended `expire_on_commit=False` default. `tenant_session` — context manager for Postgres RLS multi-tenancy (`SET LOCAL app.current_tenant = '<uuid>'`); UUID-validated to prevent SQL injection. |
+
+**FastAPI helpers live elsewhere.** The `get_session`
+FastAPI-Depends generator and the `setup_db` lifespan helper that
+previously co-located with these in mgf-common moved to
+[`mgf.fastapi.db`](https://pypi.org/project/mgf-fastapi/) in
+mgf-fastapi v0.2.0 (which depends on mgf-sqlalchemy via its
+`[sqlalchemy]` extra). This sibling stays framework-agnostic — no
+Starlette / no FastAPI in the dependency graph.
+
+## Install
+
+```bash
+pip install mgf-sqlalchemy
+# Or with the test extra (aiosqlite for in-memory SQLite tests):
+pip install 'mgf-sqlalchemy[test]'
+```
+
+Pulls in `mgf-common` + `sqlalchemy[asyncio]` automatically. Production
+consumers also need an async driver of their own (asyncpg / aiomysql /
+asyncmy); we don't pin one — the consumer picks based on their
+database.
+
+## Quick start
+
+```python
+import asyncio
+from mgf.sqlalchemy import create_engine, create_sessionmaker
+
+async def main() -> None:
+    engine = create_engine(
+        "postgresql+asyncpg://user:pass@localhost/myapp",
+        echo=False,
+    )
+    sessionmaker = create_sessionmaker(engine)
+    try:
+        async with sessionmaker() as session:
+            from sqlalchemy import text
+            row = (await session.execute(text("SELECT 1"))).scalar_one()
+            print(row)
+    finally:
+        await engine.dispose()
+
+asyncio.run(main())
+```
+
+## Postgres RLS multi-tenancy
+
+```python
+from uuid import UUID
+from mgf.sqlalchemy import tenant_session
+
+tenant_id = UUID("550e8400-e29b-41d4-a716-446655440000")
+
+async with sessionmaker() as session:
+    async with tenant_session(session, tenant_id) as scoped:
+        # Every query on `scoped` (same session, just tenant-scoped)
+        # gets `app.current_tenant` set in the current transaction.
+        # RLS policies in your schema can read from
+        # `current_setting('app.current_tenant')`.
+        rows = await scoped.execute(text("SELECT ..."))
+```
+
+## FastAPI integration
+
+The FastAPI-shaped helpers (request-scoped session injection +
+lifespan) live in mgf-fastapi:
+
+```python
+# pyproject.toml
+dependencies = [
+    "mgf-common>=0.30,<0.31",
+    "mgf-sqlalchemy>=0.1,<0.2",
+    "mgf-fastapi[sqlalchemy]>=0.2,<0.3",
+]
+```
+
+```python
+from typing import Annotated
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from mgf.fastapi.db import get_session, setup_db
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with setup_db(app, database_url="postgresql+asyncpg://..."):
+        yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/users")
+async def list_users(
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> list[dict]:
+    ...
+```
+
+## Documentation
+
+- [`docs/recipes/sqlalchemy.md`](docs/recipes/sqlalchemy.md) — full async-SQLAlchemy walkthrough.
+- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.30 split + the get_session/setup_db relocation to mgf-fastapi).
+- [`PUBLIC_API.md`](PUBLIC_API.md) — full public surface contract.
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+
+For the federation-wide engineering standards (DESIGN_PRINCIPLES,
+ERROR_HANDLING, SECURITY, etc.) see
+[`mgf-common/docs/standards/`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/).
+This sibling inherits them by reference; the standards
+source-of-truth lives in mgf-common.
+
+## Status
+
+🚧 **Experimental** — every public name is `experimental` per AP-09.
+Promotion to `stable` happens release-by-release as consumer feedback
+in [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/FEEDBACK.md)
+converges. The 0.x window applies. Pin tightly:
+`mgf-sqlalchemy = ">=0.X.0,<0.Y"`.
+
+## Cross-references
+
+- **Filing process for sharp edges**: open an entry on
+  [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/FEEDBACK.md)
+  with `[mgf-sqlalchemy]` prefix, OR file directly on this repo's
+  Issues → maintainer mirrors into the canonical FEEDBACK.md.
+- **Federation pattern**:
+  [`mgf-common/docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/design/federation.md).
+- **The split that created this sibling**:
+  [`mgf-common/docs/release/federation_roadmap.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/release/federation_roadmap.md).
+- **Companion sibling**: [`mgf-alembic`](https://pypi.org/project/mgf-alembic/) — async-aware alembic env.py helper (paired ship at v0.30; depends on this sibling).