Metadata-Version: 2.4
Name: mgf-alembic
Version: 0.1.0
Summary: Async-aware alembic env.py helper for mgf-common consumers — one-call configure_env replaces ~40 lines of boilerplate. Sibling of mgf-common under the mgf.* namespace; pairs with mgf-sqlalchemy.
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-alembic
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-alembic/issues
Project-URL: Changelog, https://codeberg.org/magogi-admin/mgf-alembic/src/branch/master/CHANGELOG.md
Author: Bassam Alsanie, mgf-alembic contributors
License: MIT
License-File: LICENSE
Keywords: alembic,async,asyncpg,configure-env,migrations,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: alembic>=1.13
Requires-Dist: mgf-common<0.31,>=0.30
Requires-Dist: mgf-sqlalchemy<0.2,>=0.1
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-alembic` — async-aware alembic env.py helper for mgf-common consumers

[![PyPI](https://img.shields.io/pypi/v/mgf-alembic)](https://pypi.org/project/mgf-alembic/)
[![Python](https://img.shields.io/pypi/pyversions/mgf-alembic)](https://pypi.org/project/mgf-alembic/)

> **Sibling of [`mgf-common`](https://pypi.org/project/mgf-common/) +
> [`mgf-sqlalchemy`](https://pypi.org/project/mgf-sqlalchemy/) under
> the `mgf.*` namespace.** Houses the async-aware alembic `env.py`
> helper that previously lived under `mgf.common.alembic.*` —
> extracted at mgf-common v0.30 / mgf-alembic v0.1 (paired with
> mgf-sqlalchemy v0.1) per the
> [federation split plan](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).

## What this provides

| Submodule | What |
|---|---|
| `mgf.alembic` | `configure_env` — one call replaces the ~40-line `env.py` boilerplate. Auto-detects sync vs async drivers from the URL prefix (`postgresql+asyncpg://`, `sqlite+aiosqlite://`, etc.). Plumbs `compare_type`, `compare_server_default`, `naming_convention`, `include_object`, `include_schemas` through to `alembic.context.configure`. |

`include_object` / `include_schemas` were added per
[PAPER-22](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
in mgf-common v0.19; carried over to mgf-alembic v0.1 unchanged.

## Install

```bash
pip install mgf-alembic
# Or with the test extra (aiosqlite for async-driver round-trip tests):
pip install 'mgf-alembic[test]'
```

Pulls in `mgf-common`, `mgf-sqlalchemy`, and `alembic>=1.13`
automatically.

## Quick start — the entire env.py

```python
# alembic/env.py
from mgf.alembic import configure_env
from myapp.config import MyAppSettings
from myapp.db.base import Base

settings = MyAppSettings()
configure_env(
    database_url=settings.database_url,
    target_metadata=Base.metadata,
)
```

That's the entire file. The helper detects offline vs online mode,
runs the migration, disposes the engine cleanly. Async drivers
(asyncpg, aiomysql, aiosqlite, asyncmy, async psycopg) are
auto-detected; sync drivers fall through the synchronous path.

## PostGIS / TimescaleDB: filter extension tables

```python
def _exclude_extensions(obj, name, type_, reflected, compare_to):
    return not (type_ == "table" and name in {"spatial_ref_sys"})

configure_env(
    database_url=settings.database_url,
    target_metadata=Base.metadata,
    include_object=_exclude_extensions,
)
```

`alembic revision --autogenerate` no longer proposes phantom drops
for extension-managed tables (PostGIS `spatial_ref_sys`,
TimescaleDB `_timescaledb_internal`, pgvector housekeeping).

## Naming-convention shape

Constraint names auto-generated by `op.create_*` are otherwise
anonymous and vary across DBs — pin them:

```python
configure_env(
    database_url=settings.database_url,
    target_metadata=Base.metadata,
    naming_convention={
        "ix": "ix_%(column_0_label)s",
        "uq": "uq_%(table_name)s_%(column_0_name)s",
        "ck": "ck_%(table_name)s_%(constraint_name)s",
        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
        "pk": "pk_%(table_name)s",
    },
)
```

## Documentation

- [`docs/recipes/alembic.md`](docs/recipes/alembic.md) — full async-alembic walkthrough.
- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.30 split).
- [`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/master/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/master/FEEDBACK.md)
converges. The 0.x window applies. Pin tightly:
`mgf-alembic = ">=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/master/FEEDBACK.md)
  with `[mgf-alembic]` 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/master/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/master/docs/release/federation_roadmap.md).
- **Companion sibling**: [`mgf-sqlalchemy`](https://pypi.org/project/mgf-sqlalchemy/) — async SQLAlchemy engine + sessionmaker + tenant-scoping (paired ship at v0.30; this sibling depends on it).
