simple-module-db 0.0.35__tar.gz → 0.0.37__tar.gz

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/.gitignore

@@ -64,3 +64,4 @@ host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
 .verify/
+/openapi.json

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_db
-Version: 0.0.35
+Version: 0.0.37
 Summary: Per-module SQLModel Base, async session, standard mixins (Audit, SoftDelete, MultiTenant, Versioned) for simple_module
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -25,7 +25,7 @@ Requires-Dist: aiosqlite>=0.20
 Requires-Dist: alembic>=1.14
 Requires-Dist: asyncpg>=0.30
 Requires-Dist: psycopg2-binary>=2.9
-Requires-Dist: simple-module-core==0.0.35
+Requires-Dist: simple-module-core==0.0.37
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: sqlmodel>=0.0.22
 Description-Content-Type: text/markdown

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_db"
-version = "0.0.35"
+version = "0.0.37"
 description = "Per-module SQLModel Base, async session, standard mixins (Audit, SoftDelete, MultiTenant, Versioned) for simple_module"
 readme = "README.md"
 license = "MIT"
@@ -28,7 +28,7 @@ dependencies = [
     # The async app code goes through asyncpg; migration env.py rewrites the
     # URL to +psycopg2 because Alembic's online migrations are sync-only.
     "psycopg2-binary>=2.9",
-    "simple_module_core==0.0.35",
+    "simple_module_core==0.0.37",
     "sqlalchemy[asyncio]>=2.0",
     "sqlmodel>=0.0.22",
 ]

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/simple_module_db/__init__.py

@@ -4,6 +4,8 @@ from simple_module_db.audit import AuditRecord
 from simple_module_db.base import create_module_base
 from simple_module_db.callbacks import OnCommitCallback
 from simple_module_db.deps import get_db
+from simple_module_db.extensions import UnsupportedDatabaseError, ensure_db_extensions
+from simple_module_db.migration_portability import drop_enums_if_postgres
 from simple_module_db.migrations import (
     build_module_metadata,
     make_include_object,
@@ -16,6 +18,8 @@ from simple_module_db.search import LIKE_ESCAPE_CHAR, like_contains_pattern, lik
 from simple_module_db.session import DatabaseState, RequestSession, init_db
 from simple_module_db.tenancy import (
     ALL_TENANTS_OPTION,
+    DEFAULT_TENANT_ID,
+    PLATFORM_TENANT_ID,
     TENANT_ID_PATTERN,
     MissingTenantError,
     TenantIsolationError,
@@ -23,26 +27,34 @@ from simple_module_db.tenancy import (
     bind_current_tenant,
     current_tenant_id,
     is_valid_tenant_id,
+    no_tenant,
     tenant_context,
 )
 from simple_module_db.transaction import CommitBeforeResponseMiddleware, finalize_session
+from simple_module_db.types import AwareDateTime, LTree, TSVector
 from simple_module_db.writes import hard_delete, mark_written
 
 __all__ = [
     "ALL_TENANTS_OPTION",
+    "DEFAULT_TENANT_ID",
     "LIKE_ESCAPE_CHAR",
+    "PLATFORM_TENANT_ID",
     "TENANT_ID_PATTERN",
     "AuditMixin",
     "AuditRecord",
+    "AwareDateTime",
     "CommitBeforeResponseMiddleware",
     "DatabaseProvider",
     "DatabaseState",
+    "LTree",
     "MissingTenantError",
     "MultiTenantMixin",
     "OnCommitCallback",
     "RequestSession",
     "SoftDeleteMixin",
+    "TSVector",
     "TenantIsolationError",
+    "UnsupportedDatabaseError",
     "VersionedMixin",
     "all_tenants",
     "bind_current_tenant",
@@ -50,6 +62,8 @@ __all__ = [
     "create_module_base",
     "current_tenant_id",
     "detect_provider",
+    "drop_enums_if_postgres",
+    "ensure_db_extensions",
     "finalize_session",
     "get_db",
     "hard_delete",
@@ -60,6 +74,7 @@ __all__ = [
     "make_include_object",
     "make_process_revision_directives",
     "mark_written",
+    "no_tenant",
     "render_item",
     "tenant_context",
 ]

simple_module_db-0.0.37/simple_module_db/_outer_joins.py

@@ -0,0 +1,97 @@
+"""Tables an ORM entity LEFT-joins in, whose criteria already sit in ``ON`` (#417).
+
+``select(Parent, func.count(Child.id)).outerjoin(Child, ...)``: the column
+wrapped in ``func.count`` strips the ORM annotation, so ``columns_clause_froms``
+lists a bare ``Table child``. ``_plain_tables`` took that for a Core
+``Model.__table__`` reference and added ``WHERE child.tenant_id = :t``, which
+is false for every row the outer join padded with NULLs — the LEFT JOIN became
+an inner one and parents without children vanished.
+
+Excluding such a table from the ``WHERE`` is only safe when something else
+filters it. That holds for exactly one shape: the target of a LEFT outer join
+is a plain ORM entity (``.outerjoin(Child, ...)``) whose class carries the
+loader criteria, because ``with_loader_criteria`` renders them into the join's
+``ON``, and an ``ON`` predicate fully filters a LEFT join's nullable side.
+A relationship path (``.outerjoin(Parent.kids)``, ``.outerjoin(Parent.kids.
+of_type(Kid))``) lands on the same ``ON`` and counts as that entity. So:
+
+* a FULL outer join (``full=True``) is deliberately NOT exempted: it preserves
+  its right side too, and an ``ON`` predicate never removes a preserved row —
+  another tenant's (or a trashed) child that fails ``ON`` still comes back as
+  an unmatched row. Only the ``WHERE`` predicate keeps it out (over-filters,
+  never leaks);
+
+* a relationship with ``secondary`` keeps the child's ``WHERE``: the child
+  sits behind an association table, outside the outer join's own ``ON``;
+* a raw ``Model.__table__`` target gets no loader criteria and keeps its
+  ``WHERE`` predicate (over-filters, never leaks);
+* an ``aliased(Model)`` target is left alone: its name never matches a table
+  name, so it was never a ``WHERE`` candidate in the first place;
+* a target whose mapper does not map exactly one table (joined inheritance)
+  is left alone, conservatively;
+* a target whose class is not in ``covered`` (the classes the caller attaches
+  loader criteria for) is left alone — no criteria, no ``ON`` predicate.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.orm import Mapper, RelationshipProperty
+
+
+def _plain(element: Any) -> Any:
+    deannotate = getattr(element, "_deannotate", None)
+    return deannotate() if deannotate is not None else element
+
+
+def orm_outer_join_tables(stmt: Any, covered: set[type] | frozenset[type]) -> list[Any]:
+    """Un-annotated tables of ORM entities ``stmt`` LEFT-outer-joins in (never FULL).
+
+    Only entities whose class is in ``covered`` count: those are the ones the
+    filter gives ``with_loader_criteria``, which is what puts their predicate
+    in ``ON``. Compare the result by identity against FROM candidates.
+    """
+    tables: list[Any] = []
+    for entry in getattr(stmt, "_setup_joins", ()):
+        # SQLAlchemy 2.0: (target, onclause, from_, {"isouter": .., "full": ..})
+        target, flags = entry[0], entry[-1]
+        # LEFT only: ON cannot filter a FULL join's preserved right side.
+        if not isinstance(flags, dict) or not flags.get("isouter") or flags.get("full"):
+            continue
+        prop = getattr(target, "property", None)
+        if isinstance(prop, RelationshipProperty):
+            mapper, table = _relationship_target(target, prop)
+        else:
+            mapper = getattr(target, "_annotations", {}).get("parententity")
+            table = _plain(target)
+        if not isinstance(mapper, Mapper) or mapper.class_ not in covered:
+            continue
+        if table is mapper.local_table and mapper.persist_selectable is mapper.local_table:
+            tables.append(table)
+    return tables
+
+
+def _relationship_target(attr: Any, prop: RelationshipProperty) -> tuple[Any, Any]:
+    """Mapper and table a ``.outerjoin(Parent.kids)`` path lands on, or ``(None, None)``.
+
+    The child's loader criteria render into that join's ``ON`` exactly as for
+    an entity target. Two shapes are refused: a ``secondary`` relationship
+    (the child sits behind an association table, with no ``ON`` guarantee for
+    the outer join itself) and an aliased ``of_type`` (aliases never matched a
+    ``WHERE`` candidate anyway).
+    """
+    if prop.secondary is not None:
+        return None, None
+    of_type = getattr(attr, "_of_type", None)
+    mapper = prop.mapper if of_type is None else of_type
+    if not isinstance(mapper, Mapper):  # aliased(Child) is an AliasedInsp
+        return None, None
+    return mapper, mapper.local_table
+
+
+def is_excluded(from_obj: Any, excluded: list[Any]) -> bool:
+    # Table-object identity on purpose: matching by name would also drop the
+    # WHERE on a raw duplicate occurrence (an alias, another FROM) of the table.
+    plain = _plain(from_obj)
+    return any(plain is t for t in excluded)

simple_module_db-0.0.37/simple_module_db/extensions.py

@@ -0,0 +1,103 @@
+"""Postgres extensions a module needs (``ModuleBase.db_extensions``).
+
+``ensure_db_extensions`` runs from the host ``env.py`` before the migrations
+do, so a revision that creates an ``ltree`` column finds the extension already
+installed. It is idempotent (``CREATE EXTENSION IF NOT EXISTS``), so it costs
+nothing on an up-to-date database.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Iterable
+from typing import Any
+
+from simple_module_core import ModuleBase
+from sqlalchemy import text
+
+from simple_module_db.types import LTree, TSVector
+
+logger = logging.getLogger(__name__)
+
+EXTENSION_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+class UnsupportedDatabaseError(RuntimeError):
+    """A module needs a database feature the configured database lacks."""
+
+
+def declared_extensions(modules: Iterable[ModuleBase]) -> dict[str, list[str]]:
+    """``{extension: [module names that declare it]}``, validated, in module order."""
+    wanted: dict[str, list[str]] = {}
+    for mod in modules:
+        for name in mod.db_extensions():
+            if not EXTENSION_NAME_PATTERN.fullmatch(name):
+                raise ValueError(
+                    f"Module {mod.meta.name!r} declares invalid database extension "
+                    f"{name!r} (must match {EXTENSION_NAME_PATTERN.pattern})"
+                )
+            owners = wanted.setdefault(name, [])
+            if mod.meta.name not in owners:
+                owners.append(mod.meta.name)
+    return wanted
+
+
+def ensure_db_extensions(connection: Any, modules: Iterable[ModuleBase]) -> list[str]:
+    """Install every extension the modules declare; return the extension names.
+
+    * Postgres: ``CREATE EXTENSION IF NOT EXISTS "<name>"``.
+    * SQLite: raises :class:`UnsupportedDatabaseError` naming the module(s) and
+      extension(s) — SQLite has none, and carrying on would fail later with a
+      less helpful message.
+    * ``connection=None`` is Alembic offline mode: the statements are emitted
+      into the generated SQL script through ``context.execute``.
+    """
+    wanted = declared_extensions(modules)
+    if not wanted:
+        return []
+
+    offline = connection is None
+    if offline:
+        from alembic import context
+
+        dialect = context.get_context().dialect.name
+    else:
+        dialect = connection.dialect.name
+
+    if dialect != "postgresql":
+        detail = "; ".join(f"{', '.join(owners)} needs {name!r}" for name, owners in wanted.items())
+        raise UnsupportedDatabaseError(
+            f"Database extensions require PostgreSQL, but the database is {dialect}: {detail}. "
+            "Point SM_DATABASE_URL at Postgres or uninstall the module."
+        )
+
+    for name in wanted:
+        statement = f'CREATE EXTENSION IF NOT EXISTS "{name}"'
+        if offline:
+            context.execute(statement)
+        else:
+            logger.info("Ensuring Postgres extension %r", name)
+            connection.execute(text(statement))
+    return list(wanted)
+
+
+def render_extension_type(obj: Any, imports: set[str] | None) -> str | None:
+    """Alembic render for ``LTree`` / ``TSVector``, or ``None`` for other types.
+
+    Rendered through our own classes (not ``postgresql.TSVECTOR``) so the same
+    revision also upgrades on SQLite, where they are ``TEXT``.
+    """
+    if isinstance(obj, (LTree, TSVector)):
+        if imports is not None:
+            imports.add("import simple_module_db.types")
+        return f"simple_module_db.types.{type(obj).__name__}()"
+    return None
+
+
+__all__ = [
+    "UnsupportedDatabaseError",
+    "declared_extensions",
+    "ensure_db_extensions",
+    "render_extension_type",
+]

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/simple_module_db/flush_guard.py

@@ -13,7 +13,7 @@ from sqlalchemy import inspect as sa_inspect
 from sqlalchemy.orm import Session
 
 from simple_module_db.mixins import MultiTenantMixin
-from simple_module_db.query_filter import is_strict
+from simple_module_db.query_filter import fallback_tenant_id, is_strict, strict_configured
 from simple_module_db.tenancy import (
     TenantIsolationError,
     current_tenant_id,
@@ -30,11 +30,30 @@ def _owner(obj: MultiTenantMixin) -> str | None:
     return obj.tenant_id
 
 
+def _stamp_unbound(session: Session) -> None:
+    """Non-strict and unscoped (unbound, or an ``all_tenants()`` block).
+
+    New rows go to the bound tenant if there is one — a bypass widens what a
+    block may *read*, it does not move its writes elsewhere — else to the
+    install's fallback (``default_tenant`` or ``DEFAULT_TENANT_ID``).
+    """
+    stamp = current_tenant_id.get() or fallback_tenant_id(session)
+    for obj in session.new:
+        if isinstance(obj, MultiTenantMixin) and obj.tenant_id is None:
+            obj.tenant_id = stamp
+
+
 def guard_flush(session: Session) -> None:
     if is_all_tenants():
+        # A bypass block is never scoped; on a single-tenant install its new
+        # rows still need a tenant to satisfy NOT NULL (strict: left to the DB).
+        if not strict_configured(session):
+            _stamp_unbound(session)
         return
     tenant_id = current_tenant_id.get()
     strict = is_strict(session)
+    if tenant_id is None and not strict:
+        _stamp_unbound(session)
 
     for obj in session.new:
         if not isinstance(obj, MultiTenantMixin):

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/simple_module_db/insert_guard.py

@@ -1,7 +1,8 @@
 """INSERT guard and statement-value helpers for the tenant query filter.
 
 Explicit ``tenant_id`` values in an insert must match the bound tenant, and
-missing ones are stamped with it (#357); the same value readers let the
+missing ones are stamped with it (#357) — or, unbound on a non-strict
+install, with the install's fallback tenant (#380); the same value readers let the
 query filter refuse an UPDATE that assigns ``tenant_id`` (#356).
 """
 
@@ -14,6 +15,7 @@ from sqlalchemy.orm import ORMExecuteState
 from simple_module_db import model_registry as registry
 from simple_module_db.tenancy import (
     ALL_TENANTS_OPTION,
+    DEFAULT_TENANT_ID,
     TenantIsolationError,
     current_tenant_id,
     is_all_tenants,
@@ -58,18 +60,25 @@ def _foreign_insert(value: Any, tenant_id: str) -> TenantIsolationError:
     )
 
 
-def guard_insert(execute_state: ORMExecuteState, *, strict: bool) -> Any:
+def guard_insert(
+    execute_state: ORMExecuteState, *, strict: bool, fallback: str = DEFAULT_TENANT_ID
+) -> Any:
     mappers = [m.class_.__name__ for m in execute_state.all_mappers if registry.flags(m.class_)[1]]
     target = getattr(execute_state.statement, "table", None)
     if not mappers and getattr(target, "name", None) in registry.tenant_table_names:
         mappers = [target.name]  # Core insert(Model.__table__)
-    if not mappers or execute_state.execution_options.get(ALL_TENANTS_OPTION, False):
+    if not mappers:
         return None
-    if is_all_tenants():
+    bypass = execute_state.execution_options.get(ALL_TENANTS_OPTION, False) or is_all_tenants()
+    if bypass and strict:
         return None
-    tenant_id = current_tenant_id.get()
+    # A non-strict bypass checks no explicit values; missing ones still get
+    # the bound tenant, else the install's fallback (#380).
+    bound = current_tenant_id.get()
+    tenant_id = None if bypass else bound
+    stamp = bound or fallback
     if getattr(execute_state.statement, "_multi_values", None):
-        return _guard_multi_values(execute_state, tenant_id, mappers[0], strict)
+        return _guard_multi_values(execute_state, tenant_id, stamp, mappers[0], strict)
     for value in assigned_tenant_ids(execute_state):
         if tenant_id is not None and value != tenant_id:
             raise _foreign_insert(value, tenant_id)
@@ -81,20 +90,18 @@ def guard_insert(execute_state: ORMExecuteState, *, strict: bool) -> Any:
     )
     if not missing:
         return None
-    if tenant_id is None:
-        if strict:
-            raise missing_tenant_error(mappers[0], "INSERT")
-        return None
+    if tenant_id is None and strict:
+        raise missing_tenant_error(mappers[0], "INSERT")
     if rows:
-        stamped = [{**r, TENANT_COLUMN: r.get(TENANT_COLUMN, tenant_id)} for r in rows]
+        stamped = [{**r, TENANT_COLUMN: r.get(TENANT_COLUMN, stamp)} for r in rows]
         payload = stamped if isinstance(execute_state.parameters, list) else stamped[0]
         return execute_state.invoke_statement(params=payload)
-    execute_state.statement = execute_state.statement.values(**{TENANT_COLUMN: tenant_id})
+    execute_state.statement = execute_state.statement.values(**{TENANT_COLUMN: stamp})
     return None
 
 
 def _guard_multi_values(
-    execute_state: ORMExecuteState, tenant_id: str | None, entity: str, strict: bool
+    execute_state: ORMExecuteState, tenant_id: str | None, stamp: str, entity: str, strict: bool
 ) -> Any:
     """``insert(M).values([{...}, {...}])``: check and stamp each row.
 
@@ -116,15 +123,13 @@ def _guard_multi_values(
                     raise _foreign_insert(value, tenant_id)
             else:
                 missing = True
-                mapping[tenant_col] = tenant_id
+                mapping[tenant_col] = stamp
             rows.append(mapping)
         groups.append(rows)
     if not missing:
         return None
-    if tenant_id is None:
-        if strict:
-            raise missing_tenant_error(entity, "INSERT")
-        return None
+    if tenant_id is None and strict:
+        raise missing_tenant_error(entity, "INSERT")
     stamped = stmt._generate()
     stamped._multi_values = tuple(groups)
     execute_state.statement = stamped

{simple_module_db-0.0.35 → simple_module_db-0.0.37}/simple_module_db/listeners.py

@@ -62,6 +62,8 @@ _OP_UPDATE = "update"
 _OP_SOFT_DELETE = "soft_delete"
 _OP_DELETE = "delete"
 
+_LISTENERS_ATTACHED = "_sm_entity_listeners_attached"
+
 
 def _entity_label(obj: object) -> str:
     """Return 'ClassName' for a mapped entity instance."""
@@ -106,7 +108,17 @@ def attach_session_listeners(session_class: type[Session]) -> None:
 
     For a process with no ``DatabaseState`` (the Celery worker's sync engine),
     call this and ``bind_engine_policy(engine, EngineTenancy(...))``.
+
+    Idempotence is a marker in the ``__dict__`` of the class or a base, not
+    ``event.contains``: SQLAlchemy keys its event registry on ``id(target)``,
+    so a fresh session class that reuses a garbage-collected one's id reads as
+    already wired and would silently get no tenant, soft-delete or write
+    listeners at all. A subclass of a wired class is skipped because SQLAlchemy
+    propagates class-level session listeners to subclasses (even ones defined
+    later); wiring it again would fire every listener twice.
     """
+    if any(base.__dict__.get(_LISTENERS_ATTACHED) for base in session_class.__mro__):
+        return
     for name, fn in (
         ("before_flush", _before_flush_listener),
         ("after_flush", _mark_session_written),
@@ -114,8 +126,8 @@ def attach_session_listeners(session_class: type[Session]) -> None:
         ("do_orm_execute", _mark_dml_written),
         ("do_orm_execute", filter_statements),
     ):
-        if not event.contains(session_class, name, fn):
-            event.listen(session_class, name, fn)
+        event.listen(session_class, name, fn)
+    setattr(session_class, _LISTENERS_ATTACHED, True)
 
 
 def _before_flush_listener(

simple_module_db-0.0.37/simple_module_db/migration_portability.py

@@ -0,0 +1,164 @@
+"""Keep revisions autogenerated on SQLite portable to PostgreSQL (GH #342).
+
+Autogenerate against the default SQLite database emits things Postgres rejects
+or never sees, and neither ``alembic check`` nor the boot check notices:
+
+* Boolean ``server_default`` rendered as ``sa.text('0')`` — Postgres refuses an
+  integer default on a boolean column. :func:`rewrite_boolean_defaults` and
+  :func:`render_boolean_default` emit ``sa.false()`` / ``sa.true()`` instead.
+* Expression indexes (``lower(email)``) are skipped on SQLite because it cannot
+  reflect them. :func:`warn_unverifiable_expression_indexes` says so loudly.
+* ``op.drop_table`` leaves ``CREATE TYPE`` behind on Postgres, so a downgrade
+  followed by an upgrade fails with ``DuplicateObject``. Use
+  :func:`drop_enums_if_postgres` in the revision's ``downgrade``.
+
+``simple_module_db.migrations`` wires the first two into the hooks every
+``env.py`` already passes to Alembic.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from typing import Any
+
+import sqlalchemy as sa
+from alembic.operations.ops import AddColumnOp, AlterColumnOp, CreateTableOp
+from simple_module_core.diagnostics._expression_index import find_expression_indexes
+from sqlalchemy.dialects import postgresql
+from sqlalchemy.schema import DefaultClause
+from sqlalchemy.sql.elements import ColumnElement, False_, TextClause, True_
+
+logger = logging.getLogger("alembic.env")
+
+_FALSE_LITERALS = frozenset({"0", "false"})
+_TRUE_LITERALS = frozenset({"1", "true"})
+
+
+def boolean_default_for(default: Any) -> ColumnElement[bool] | None:
+    """Map a Boolean ``server_default`` spelled as 0/1/true/false to ``sa.false()``/``sa.true()``.
+
+    Accepts a ``DefaultClause``, ``text()``, bare string, or SQLAlchemy
+    ``true()``/``false()``; returns ``None`` when it is none of those literals.
+    """
+    arg = default.arg if isinstance(default, DefaultClause) else default
+    if isinstance(arg, False_):
+        return sa.false()
+    if isinstance(arg, True_):
+        return sa.true()
+    text = arg.text if isinstance(arg, TextClause) else arg
+    if not isinstance(text, str):
+        return None
+    literal = text.strip().strip("()").strip("'\"").lower()
+    if literal in _FALSE_LITERALS:
+        return sa.false()
+    if literal in _TRUE_LITERALS:
+        return sa.true()
+    return None
+
+
+def render_boolean_default(obj: Any, autogen_context: Any) -> str | bool:
+    """``render_item`` branch: render ``true()``/``false()`` defaults as such.
+
+    SQLAlchemy compiles ``false()`` under SQLite to ``0``, which Alembic then
+    renders as ``sa.text('0')``. Intercepting the ``server_default`` item keeps
+    the portable expression the model declared.
+    """
+    arg = obj.arg if isinstance(obj, DefaultClause) else obj
+    if not isinstance(arg, (True_, False_)):
+        return False
+    prefix = autogen_context.opts.get("sqlalchemy_module_prefix", "sa.")
+    return f"{prefix}{'true' if isinstance(arg, True_) else 'false'}()"
+
+
+def iter_ops_recursive(container: Any) -> Iterator[Any]:
+    """Yield every op under ``container``, descending into nested op groups.
+
+    Autogenerate does not emit a flat op list: index operations for a table are
+    grouped inside a ``ModifyTableOps`` container alongside the top-level
+    ``CreateTableOp``/``DropTableOp``. A dedup check that only looks at
+    ``container.ops`` therefore sees no ``CreateIndexOp`` at all and re-injects
+    an index the dialect already emitted — which is exactly how a dialect that
+    *can* reflect expression-based indexes (PostgreSQL) ended up with a
+    duplicate ``CREATE INDEX`` in its initial migration.
+    """
+    for op in container.ops:
+        yield op
+        if hasattr(op, "ops"):
+            yield from iter_ops_recursive(op)
+
+
+def rewrite_boolean_defaults(upgrade_ops: Any) -> None:
+    """Rewrite integer-looking defaults on Boolean columns in a revision's op tree.
+
+    Covers columns of ``create_table``, ``add_column`` and ``alter_column``
+    (the latter via ``existing_type``).
+    """
+    for op in iter_ops_recursive(upgrade_ops):
+        if isinstance(op, CreateTableOp):
+            columns = [c for c in op.columns if isinstance(c, sa.Column)]
+        elif isinstance(op, AddColumnOp):
+            columns = [op.column]
+        elif isinstance(op, AlterColumnOp):
+            replacement = None
+            if isinstance(op.existing_type or op.modify_type, sa.Boolean):
+                replacement = boolean_default_for(op.modify_server_default)
+            if replacement is not None:
+                op.modify_server_default = replacement
+            continue
+        else:
+            continue
+        for column in columns:
+            if not isinstance(column.type, sa.Boolean) or column.server_default is None:
+                continue
+            replacement = boolean_default_for(column.server_default)
+            if replacement is not None:
+                column.server_default = DefaultClause(replacement)
+
+
+def warn_unverifiable_expression_indexes(dialect_name: str | None, metadata: sa.MetaData) -> list:
+    """Warn when autogenerating on SQLite while models declare expression indexes.
+
+    A warning rather than an error: autogenerate also runs for ordinary,
+    unrelated revisions, and failing every one of them for an index that is
+    already in history would block normal work. The warning is emitted on every
+    run, names each index, and ``alembic check`` on Postgres
+    (``make migrations-roundtrip-pg``) is the real gate. Returns the
+    ``(table, index)`` pairs it warned about.
+    """
+    if dialect_name != "sqlite":
+        return []
+    found = find_expression_indexes(metadata.tables.values())
+    if not found:
+        return []
+    listing = "\n".join(f"    - {index} on {table}" for table, index in found)
+    logger.warning(
+        "\n%s\n"
+        "WARNING: autogenerating on SQLite. SQLite cannot reflect expression indexes,\n"
+        "so this revision does NOT account for the following (they are neither\n"
+        "created nor verified here) and `alembic check` will not notice drift:\n"
+        "%s\n"
+        "Add them to the revision by hand and verify on PostgreSQL before merging\n"
+        "(`make migrations-roundtrip-pg`). See docs/module-authoring.md, Migrations.\n"
+        "%s",
+        "=" * 78,
+        listing,
+        "=" * 78,
+    )
+    return found
+
+
+def drop_enums_if_postgres(op: Any, *names: str) -> None:
+    """Drop the named enum types on PostgreSQL; a no-op elsewhere.
+
+    Call it at the end of ``downgrade()``, after the tables that use the types
+    are dropped. ``op.drop_table`` leaves the ``CREATE TYPE`` behind, and
+    autogenerate never emits the ``Enum.drop``, so without this a
+    ``downgrade`` followed by an ``upgrade`` fails with ``DuplicateObject``.
+    SQLite has no such object, which is why the round trip passes there.
+    """
+    bind = op.get_bind()
+    if bind.dialect.name != "postgresql":
+        return
+    for name in names:
+        postgresql.ENUM(name=name).drop(bind, checkfirst=True)