Connection & Registry¶

async def connect(
    url: str,
    auto_migrate: bool = False,
    name: str | None = None,
    default: bool = False,
    pool: PoolConfig | None = None,
    *,
    identity_map: bool = True,
    migrate_updates: bool = False,
    migrate_destructive: bool = False,
) -> None:
    """
    Establish a connection to the database.

    Args:
        url: The database connection string (e.g., "sqlite:example.db?mode=rwc").
        auto_migrate: If True, automatically create tables for all registered models.
            Existing tables are left completely untouched — whatever their shape —
            unless ``migrate_updates`` / ``migrate_destructive`` are also set.
        name: Optional connection name. Omitted connections register as "default".
        default: If True, make this named connection the default for unqualified operations.
        pool: Optional per-connection pool configuration.
        identity_map: If True (default), sessions opened on this connection keep an identity
            map so the same primary key maps to a single Python instance within a session.
            Identity maps are session-scoped: operations outside a session never cache or
            dedup instances. If False, loads on this connection return fresh instances even
            inside a session (lower memory use; no ``a is b`` guarantees across loads).
        migrate_updates: If True, additionally update existing tables to match the
            registered models. Implies ``auto_migrate``. What this covers is
            capability-relative per backend:

            - **Both backends**: ``ALTER TABLE ... ADD COLUMN`` for model fields
              missing from the live table, using the same column DDL ``CREATE TABLE``
              would emit (including single-column indexes and, on Postgres, CHECK
              constraints and foreign keys). NOT NULL fields need a literal default
              to backfill existing rows — connecting fails with a clear error
              otherwise.
            - **Postgres only**: column type changes
              (``ALTER COLUMN ... TYPE ... USING`` cast) and nullability changes
              (``SET/DROP NOT NULL``) when the live column disagrees with the model.
              Also foreign-key reconciliation: a ferro-owned (``fk_``-named)
              constraint whose definition drifts from the declared FK
              (``on_delete``, target) is rebuilt (``DROP CONSTRAINT`` +
              ``ADD CONSTRAINT``), and a declared FK missing entirely from an
              existing column is added. A drifting constraint ferro does not
              own is warned about, never altered.
            - **SQLite**: type/nullability drift cannot be changed in place; ferro
              emits a ``UserWarning`` naming the column and pointing at Alembic.
              (SQLite's type affinity makes declared-type drift mostly cosmetic.)
              FK constraints likewise cannot be added or altered on an existing
              table; any foreign-key drift warns loudly instead of diverging
              silently.
            - **Transactionality**: on Postgres each table's migration plan
              runs inside a single transaction — a mid-plan failure rolls the
              table back to exactly its pre-migration state. On SQLite,
              statements apply one at a time; a mid-run failure can leave
              earlier statements of that table applied (SQLite ALTERs are
              single-statement operations). For transactional multi-step
              SQLite migrations, use the Alembic bridge.

            After any schema change, the connection pool is refreshed so no cached
            statement can observe the pre-migration schema.
        migrate_destructive: If True, additionally **drop** live columns that no
            longer exist on the model (never whole tables). Implies
            ``migrate_updates``. Dropping is dependency-aware: explicit indexes
            covering the column are dropped first; columns that are primary keys or
            enforced by table constraints fail with a clear error instead.

    Raises:
        ValueError: A connection with this name (or a default connection,
            when ``name`` is omitted) is already registered. Use ``name=...``
            for additional connections or ``reset_engine()`` to tear down.

    For schema changes beyond these (renames, primary-key changes, complex
    transforms), use the Alembic bridge — see ``docs/guide/migrations.md``.
    """
    _ensure_rust_registration_synced()

    pool_config = pool or PoolConfig()
    await _core_connect(
        url,
        auto_migrate=auto_migrate,
        name=name,
        default=default,
        max_connections=pool_config.max_connections,
        min_connections=pool_config.min_connections,
        identity_map=identity_map,
        migrate_updates=migrate_updates,
        migrate_destructive=migrate_destructive,
    )

def set_default_connection(name: str) -> None: ...

def reset_engine() -> None: ...

async def create_tables(using=None):
    """
    Manually create the *missing* tables for registered models on a connected
    engine. A table that already exists is left completely untouched; altering
    existing tables belongs to ``migrate(updates=True)``.

    Compiles and pushes the current registry SchemaIR to the Rust runtime
    before delegating to the Rust create entrypoint, so a model defined after
    ``connect()`` (and thus absent from the connect-time snapshot) is still
    created. The runtime emits each ``CREATE TABLE`` from this SchemaIR via the
    shared emitter.

    Args:
        using: Named connection to create tables on, or None for the default.
    """
    _ensure_rust_registration_synced()
    return await _core_create_tables(using=using)

async def migrate(using=None, updates=True, destructive=False):
    """
    Manually run the auto-migrate pass against a connected engine.

    Compiles and pushes the current registry SchemaIR to the Rust runtime,
    then delegates to the Rust migrate entrypoint.

    Args:
        using: Named connection to migrate, or None for the default.
        updates: If True (default), add missing columns and reconcile
            type, nullability, and foreign-key definition drift (see ``connect``).
        destructive: If True, also drop live columns absent from the model. Implies ``updates``.
    """
    _ensure_rust_registration_synced()
    return await _core_migrate(using=using, updates=updates, destructive=destructive)

def clear_registry() -> None:
    """Reset the compiled/registered schema state.

    Delegates to the Rust core (which clears the Rust model registry and the
    pushed SchemaIR modelset) and additionally clears the Python **join-table
    registry**. That registry must be reset here because
    ``connect``/``create_tables``/``migrate`` compile the *full* registry via
    ``compile_registry_schema_ir()``: a join table left behind by a prior run
    would be re-created with foreign keys to tables that no longer exist —
    tolerated by SQLite but rejected by Postgres (``relation ... does not
    exist``). (#153)

    The Python model registry is intentionally **not** cleared here: clearing
    the Rust registry while keeping the declared Python models is what allows
    cold re-hydration after ``reset_engine`` (see
    ``tests/test_enum_cold_hydration.py``). Callers that want a full
    Python-side reset use ``REGISTRY.reset_for_test()``.

    Each purged join table's compiled SchemaIR envelope is evicted with it —
    ``Registry.clear_join_tables`` owns that agreement (#153): a lingering
    join envelope would let a future assemble step resurrect the stale join
    table.
    """
    _core_clear_registry()
    from .registry import REGISTRY

    REGISTRY.clear_join_tables()

def evict_instance(
    model: "type[Model] | str",
    pk: str,
    *,
    using: str | None = None,
    session: "Session | None" = None,
) -> None:
    """Remove one instance from the active scope's identity map.

    ``model`` is a model class, its qualified identity, or an unambiguous
    bare class name (ambiguity raises with the candidates listed).

    Public wrapper around the FFI `evict_instance` (FF-D D3): resolves the
    route once via `resolve_operation_scope`, then passes it through. Model
    instance methods (`save`/`delete`/`refresh`) call the FFI symbol
    directly with their already-resolved route instead of going through this
    wrapper, so a route is never resolved twice for one operation.
    """
    from .registry import REGISTRY

    model_cls = REGISTRY.resolve_reference(model) if isinstance(model, str) else model
    route = resolve_operation_scope(using=using, session=session)
    _core_evict_instance(model_cls.__ferro_identity__, pk, route)

def version() -> str: ...