mgf-sqlalchemy 0.1.0__py3-none-any.whl

mgf/sqlalchemy/__init__.py

@@ -0,0 +1,47 @@
+"""``mgf.sqlalchemy`` — async SQLAlchemy helpers for mgf-common consumers.
+
+Sibling of :mod:`mgf.common` under the ``mgf.*`` namespace. Houses the
+async-engine factory + sessionmaker + tenant-RLS helper that previously
+lived under ``mgf.common.db.*`` — extracted at mgf-common v0.30 /
+mgf-sqlalchemy v0.1 per the federation split plan.
+
+Every async-SQLAlchemy consumer needs the same three things:
+
+  - An :class:`AsyncEngine` factory with sane defaults (pool sizing,
+    ``pool_pre_ping``, ``pool_recycle``, ``echo`` from settings).
+  - An :func:`async_sessionmaker` factory wired to that engine.
+  - A per-request tenant-scoping context manager
+    (``SET LOCAL app.current_tenant = '<uuid>'`` for Postgres RLS).
+
+This sibling is **framework-agnostic**: no FastAPI, no Starlette, no
+Django imports. The FastAPI-Depends-shaped ``get_session`` and the
+``setup_db`` lifespan helper that previously lived under
+``mgf.common.db`` were moved to the :mod:`mgf.fastapi.db` submodule
+in mgf-fastapi v0.2.0 (which depends on mgf-sqlalchemy via the
+``[sqlalchemy]`` extra). See ``mgf-sqlalchemy/docs/cutover/v0.1.0.md``
+for the full migration map.
+
+Install: ``pip install mgf-sqlalchemy`` (pulls
+``sqlalchemy[asyncio]>=2.0``). For tests against an in-memory SQLite
+database: ``pip install 'mgf-sqlalchemy[test]'`` (adds ``aiosqlite``).
+
+The integration is **adapter-shaped, not framework-shaped**. Nothing
+here re-exports SQLAlchemy primitives or hides them. The consumer's
+ORM is still vanilla SQLAlchemy 2; these helpers plug into the seams
+(engine factory, sessionmaker).
+
+Closed-box invariant: ``mgf-sqlalchemy`` depends on ``mgf-common`` +
+``sqlalchemy`` only. Consumers MUST import from ``mgf.sqlalchemy``,
+never reach into ``mgf.sqlalchemy._engine`` / ``mgf.sqlalchemy._session``.
+"""
+
+from __future__ import annotations
+
+from mgf.sqlalchemy._engine import create_engine
+from mgf.sqlalchemy._session import create_sessionmaker, tenant_session
+
+__all__ = [
+    "create_engine",
+    "create_sessionmaker",
+    "tenant_session",
+]

mgf/sqlalchemy/_engine.py

@@ -0,0 +1,84 @@
+"""Async SQLAlchemy engine factory.
+
+Wraps :func:`sqlalchemy.ext.asyncio.create_async_engine` with
+production-leaning defaults:
+
+  - ``pool_pre_ping=True`` — every checkout pings the connection.
+    Costs one round-trip per checkout but catches stale connections
+    after DB restart / firewall reset / etc.
+  - ``pool_recycle=3600`` — recycle connections older than an hour.
+    Avoids the MySQL "wait_timeout" surprise + Postgres connection
+    leaks.
+  - ``pool_size`` / ``max_overflow`` set to conservative defaults
+    that work for SQLite + scale to Postgres / MySQL.
+
+Consumers override any default via kwargs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+# Production-leaning defaults. Override per-consumer as needed.
+_DEFAULT_POOL_PRE_PING: bool = True
+_DEFAULT_POOL_RECYCLE_SECONDS: int = 3600  # 1 hour
+_DEFAULT_POOL_SIZE: int = 5
+_DEFAULT_MAX_OVERFLOW: int = 10
+
+
+def create_engine(
+    database_url: str,
+    *,
+    echo: bool = False,
+    pool_pre_ping: bool = _DEFAULT_POOL_PRE_PING,
+    pool_recycle: int = _DEFAULT_POOL_RECYCLE_SECONDS,
+    pool_size: int = _DEFAULT_POOL_SIZE,
+    max_overflow: int = _DEFAULT_MAX_OVERFLOW,
+    **extra: Any,
+) -> AsyncEngine:
+    """Build an async SQLAlchemy engine with mgf defaults.
+
+    ``database_url`` follows the SQLAlchemy URL grammar — must use
+    an async driver:
+
+      - ``postgresql+asyncpg://user:pass@host/db``
+      - ``mysql+aiomysql://...``
+      - ``sqlite+aiosqlite://`` (in-memory) or
+        ``sqlite+aiosqlite:///path/to/db.sqlite``
+
+    ``echo=True`` logs every statement (debug only — never in prod).
+
+    Pool settings are passed through to SQLAlchemy. SQLite ignores
+    ``pool_size`` / ``max_overflow`` (it uses ``StaticPool`` /
+    ``NullPool``) — the values are still accepted for shape
+    consistency but have no effect.
+
+    ``**extra`` is forwarded to :func:`create_async_engine` for
+    consumers needing rare options (``connect_args``, ``isolation_level``,
+    ``poolclass``, etc.).
+
+    Returns the engine. The engine is **not yet connected** — the
+    first connection attempt happens lazily on the first
+    ``await engine.connect()`` or ``async_sessionmaker()`` call.
+    """
+    kwargs: dict[str, Any] = {
+        "echo": echo,
+        "pool_pre_ping": pool_pre_ping,
+        "pool_recycle": pool_recycle,
+    }
+
+    # Pool sizing only applies to drivers that use a real pool.
+    # SQLite uses StaticPool / NullPool; passing pool_size to those
+    # raises. Detect the driver and skip pool kwargs accordingly.
+    is_sqlite = database_url.startswith(("sqlite://", "sqlite+"))
+    if not is_sqlite:
+        kwargs["pool_size"] = pool_size
+        kwargs["max_overflow"] = max_overflow
+
+    kwargs.update(extra)
+    return create_async_engine(database_url, **kwargs)
+
+
+__all__ = ["create_engine"]

mgf/sqlalchemy/_session.py

@@ -0,0 +1,105 @@
+"""Async sessionmaker + tenant-scoping helper.
+
+Two helpers covering the request-handling lifecycle:
+
+  - :func:`create_sessionmaker` — wraps :class:`async_sessionmaker`
+    with mgf defaults (``expire_on_commit=False`` — SQLAlchemy 2's
+    recommended default for async; consumers can pass
+    ``expire_on_commit=True`` to opt into the legacy behavior).
+  - :func:`tenant_session` — 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. Tenant id is
+    UUID-validated at the call site to prevent SQL injection.
+
+The FastAPI-Depends-shaped ``get_session`` previously co-located here
+was moved to :mod:`mgf.fastapi.db` in mgf-fastapi v0.2 — it depends
+on Starlette/FastAPI's ``Request`` / ``app.state`` which would pull a
+heavy framework dep into this otherwise-pure sibling.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from sqlalchemy.ext.asyncio import AsyncEngine
+
+
+def create_sessionmaker(
+    engine: AsyncEngine,
+    *,
+    expire_on_commit: bool = False,
+) -> async_sessionmaker[AsyncSession]:
+    """Return an :class:`async_sessionmaker` bound to ``engine``.
+
+    Default ``expire_on_commit=False`` matches SQLAlchemy 2's
+    recommended default for async sessions (objects stay usable
+    after commit instead of being silently expired). Pass
+    ``expire_on_commit=True`` to revert to the legacy synchronous
+    semantics.
+    """
+    return async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        expire_on_commit=expire_on_commit,
+    )
+
+
+@asynccontextmanager
+async def tenant_session(
+    session: AsyncSession,
+    tenant_id: str | UUID,
+) -> AsyncIterator[AsyncSession]:
+    """Run ``SET LOCAL app.current_tenant = '<tenant_id>'`` for ``session``.
+
+    Postgres RLS-based multi-tenancy pattern. The ``LOCAL`` qualifier
+    scopes the setting 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`` does NOT accept bind parameters, so we have to
+    interpolate the value into the SQL — which is safe iff the
+    input is shape-validated (UUIDs are alphanumeric + dashes,
+    no SQL-meaningful chars). A non-UUID input raises ``ValueError``.
+
+    Raises ``ValueError`` if ``tenant_id`` isn't a UUID-shaped
+    string; raises whatever SQLAlchemy raises if the database
+    rejects the SET (e.g., custom GUC not declared in
+    ``postgresql.conf``).
+
+    Use as::
+
+        async with sessionmaker() as session:
+            async with tenant_session(session, tenant_id) as scoped:
+                # All queries on `scoped` (same session, just
+                # tenant-scoped) get app.current_tenant.
+                rows = await scoped.execute(text("SELECT ..."))
+    """
+    if isinstance(tenant_id, UUID):
+        tenant_str = str(tenant_id)
+    else:
+        # Validate that the string is a real UUID; UUID() raises
+        # ValueError on malformed input. After validation, the
+        # canonical hex+dash form is safe to interpolate.
+        validated = UUID(tenant_id)
+        tenant_str = str(validated)
+
+    # SET LOCAL accepts only literal values; bind params don't work.
+    # Safe because tenant_str came from UUID() — alphanumeric+dashes.
+    await session.execute(text(f"SET LOCAL app.current_tenant = '{tenant_str}'"))
+    yield session
+
+
+__all__ = [
+    "create_sessionmaker",
+    "tenant_session",
+]

mgf_sqlalchemy-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+mgf/sqlalchemy/__init__.py,sha256=BG51-RLTY_RUCKRTtYiU7-3rSYHKE8m9V7J_UxTdfhg,2030
+mgf/sqlalchemy/_engine.py,sha256=2ofgYljzOxjoeVp5kmv0Bhq2WDUsDFgaG2QkOTiPq8c,2891
+mgf/sqlalchemy/_session.py,sha256=IRT6y61ODm9BuA3yx-mPWAjJACMR1CLkqjPcGbNq8vE,3850
+mgf/sqlalchemy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mgf_sqlalchemy-0.1.0.dist-info/METADATA,sha256=Me6qLm1JBn14u6lxmXBpYoInbZlvHqul5wUTMneqP8M,7580
+mgf_sqlalchemy-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mgf_sqlalchemy-0.1.0.dist-info/licenses/LICENSE,sha256=akPl7tlbK9cB--mcmU-3T3VYoIpSXQUJd3DDpztyDFc,1099
+mgf_sqlalchemy-0.1.0.dist-info/RECORD,,

mgf_sqlalchemy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mgf_sqlalchemy-0.1.0.dist-info/licenses/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.