cleveragents-core/tools/controller/db/migrations.py

"""Additive schema migrations for the controller DB.

The project does not run Alembic — ``create_all`` (declarative
``Base.metadata.create_all``) handles schema for fresh databases.
That covers test DBs and first-time installs cleanly, but adds
nothing to a DB that already has the table from a prior version.

When a column is added to an existing model, live deployments need
an additive migration. We keep this minimal: idempotent ``ALTER
TABLE ... ADD COLUMN ...`` per dialect, wired into ``create_all``
so the next controller startup picks it up.

This is NOT a versioned migration framework. Each step is a single
idempotent SQL statement that assumes the column either does not
exist (then add it) or already exists (then no-op). Order does not
matter; the steps are independent.

When the schema becomes complex enough that this pattern breaks
(e.g. needing data backfills or renames), graduate to Alembic.
"""

from __future__ import annotations

import logging
from typing import NamedTuple

from sqlalchemy import Engine, text
from sqlalchemy.exc import OperationalError, ProgrammingError

logger = logging.getLogger(__name__)


class _AdditiveColumn(NamedTuple):
    """An additive column migration step.

    ``sqlite_decl`` is the type clause for SQLite (e.g. ``"TEXT"``).
    ``postgres_decl`` is the type clause for Postgres (e.g. ``"VARCHAR(32)"``).
    Both are NULL-allowed (the table already has rows; a non-NULL
    column would require a backfill, which this module does not do).
    """

    table: str
    column: str
    sqlite_decl: str
    postgres_decl: str


# Append new column migrations here. Each step is independent + idempotent.
_ADDITIVE_COLUMNS: tuple[_AdditiveColumn, ...] = (
    # Phase 0 (grooming plan): controller_events.cause for action
    # attribution. See contracts/causes.py and the plan's decision #23.
    _AdditiveColumn(
        table="controller_events",
        column="cause",
        sqlite_decl="TEXT",
        postgres_decl="VARCHAR(32)",
    ),
    # Phase 0 (grooming plan): workflows columns for one-shot semantics
    # and the defer block. See decisions #15, #16, #17 and the Phase 1
    # schema-additions section (pulled forward to Phase 0 because the
    # close_issue/defer_issue callbacks depend on them).
    _AdditiveColumn(
        table="workflows",
        column="grooming_evaluated_at",
        sqlite_decl="TEXT",
        postgres_decl="TIMESTAMP WITH TIME ZONE",
    ),
    _AdditiveColumn(
        table="workflows",
        column="deferred_reason",
        sqlite_decl="TEXT",
        postgres_decl="VARCHAR(32)",
    ),
    _AdditiveColumn(
        table="workflows",
        column="deferred_at",
        sqlite_decl="TEXT",
        postgres_decl="TIMESTAMP WITH TIME ZONE",
    ),
    _AdditiveColumn(
        table="workflows",
        column="deferred_target_workflow_id",
        sqlite_decl="INTEGER",
        postgres_decl="INTEGER",
    ),
)


def apply_additive_migrations(engine: Engine) -> None:
    """Apply every additive column migration that is missing.

    Idempotent: re-running on a fully-up-to-date DB is a no-op
    (each step swallows the dialect-specific "column already exists"
    error). Safe to call from ``create_all``.
    """
    dialect = engine.dialect.name  # 'sqlite' or 'postgresql'
    with engine.begin() as conn:
        for step in _ADDITIVE_COLUMNS:
            if dialect == "postgresql":
                # Postgres 9.6+ has IF NOT EXISTS for ADD COLUMN.
                conn.execute(
                    text(
                        f"ALTER TABLE {step.table} "
                        f"ADD COLUMN IF NOT EXISTS {step.column} "
                        f"{step.postgres_decl}"
                    )
                )
                logger.debug(
                    "migrations: ensured column %s.%s (postgres)",
                    step.table,
                    step.column,
                )
                continue

            # SQLite has no IF NOT EXISTS for ADD COLUMN before 3.35;
            # catch the duplicate-column OperationalError instead.
            try:
                conn.execute(
                    text(
                        f"ALTER TABLE {step.table} "
                        f"ADD COLUMN {step.column} {step.sqlite_decl}"
                    )
                )
                logger.info(
                    "migrations: added column %s.%s (sqlite)",
                    step.table,
                    step.column,
                )
            except (OperationalError, ProgrammingError) as exc:
                msg = str(exc).lower()
                if "duplicate column" in msg or "already exists" in msg:
                    logger.debug(
                        "migrations: column %s.%s already present (sqlite)",
                        step.table,
                        step.column,
                    )
                    continue
                # Any other OperationalError is a real failure — let it surface.
                raise


__all__ = ["apply_additive_migrations"]