ss-tools/backend/alembic/env.py

# #region Alembic.Env.AlembicEnvModule [C:3] [TYPE Module] [SEMANTICS alembic, migration, env, logging]
# @BRIEF Alembic environment configuration — sets up DB connection, model metadata,
#   and logging. Contains ADR [LOG-001] for suppress_existing_loggers=False.
# @LAYER Infrastructure
# @RELATION DEPENDS_ON -> [Core.Logger.LoggerModule]
# @INVARIANT fileConfig() must be called with disable_existing_loggers=False
#   to prevent disabling superset_tools_app logger (see ADR LOG-001).
# #endregion Alembic.Env.AlembicEnvModule

from logging.config import fileConfig
import os
from pathlib import Path
import sys

from sqlalchemy import engine_from_config, pool

from alembic import context

# Ensure backend/src is importable
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Allow overriding sqlalchemy.url via DATABASE_URL env var
if "DATABASE_URL" in os.environ:
    config.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])

# Interpret the config file for Python logging.
# This line sets up loggers basically.
# @NOTE [LOG-001] disable_existing_loggers=False
# @RATIONALE Python 3.13's logging.config.fileConfig() defaults to
#   disable_existing_loggers=True, which sets logger.disabled = True on ALL
#   existing loggers not listed in alembic.ini's [loggers] section. This
#   includes our 'superset_tools_app' and 'cot' loggers. With disabled=True,
#   Logger.isEnabledFor() immediately returns False (see Python 3.13 source),
#   silently dropping every logger.info()/warning()/error() call across the
#   entire application. The SS-TOOLS logging system manages its own handlers
#   via configure_logger() — Alembic's INI-based config is irrelevant here.
# @REJECTED Adding superset_tools_app to alembic.ini [loggers] was rejected
#   because it couples app logging config to Alembic's ini format, which is
#   fragile and non-obvious for future maintainers.
if config.config_file_name is not None:
    fileConfig(config.config_file_name, disable_existing_loggers=False)

# add your model's MetaData object here
# for 'autogenerate' support
# Import every ORM module so the baseline metadata is complete.
import src.models  # noqa: F401, E402
from src.models import (  # noqa: F401, E402
    agent,
    agent_run,
    api_key,
    assistant,
    auth,
    clean_release,
    config as models_config,
    dashboard,
    dashboard_release,
    deployment,
    filter_state,
    git,
    lineage,
    llm,
    load_testing,
    maintenance,
    mapping,
    profile,
    report,
    scenario_approval,
    scenario_artifact,
    scenario_automation,
    scenario_checkpoint,
    scenario_investigation,
    scenario_registry,
    scenario_run,
    scenario_worker,
    storage,
    task,
    translate,
    verification_run,
)
from src.models.mapping import Base  # noqa: E402
from src.core.env_settings import (  # noqa: E402
    database_connect_args,
    database_schema,
)

target_metadata = Base.metadata


# #region Alembic.Env.VersionTableSchema [C:1] [TYPE Function]
# @BRIEF Explicit version-table schema for non-public deployments; None keeps the default schema.
def _version_table_schema() -> str | None:
    schema = database_schema()
    return None if schema == "public" else schema
# #endregion Alembic.Env.VersionTableSchema

# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.


def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode.

    This configures the context with just a URL
    and not an Engine, though an Engine is acceptable
    here as well.  By skipping the Engine creation
    we don't even need a DBAPI to be available.

    Calls to context.execute() here emit the given string to the
    script output.

    """
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
        version_table_schema=_version_table_schema(),
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    external_connection = config.attributes.get("connection")
    if external_connection is not None:
        context.configure(
            connection=external_connection,
            target_metadata=target_metadata,
            version_table_schema=_version_table_schema(),
        )
        with context.begin_transaction():
            context.run_migrations()
        return

    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
        connect_args=database_connect_args(),
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            version_table_schema=_version_table_schema(),
        )

        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()