alembic-knowledge-patch

# Alembic Knowledge Patch Use this skill when changing an Alembic project, reviewing generated migrations, upgrading Alembic, extending its CLI or operation system, or diagnosing revision graph and backend-specific DDL behavior. Inspect the project's pinned Alembic, Python, and SQLAlchemy versions before applying version-dependent advice. Prefer the project's code, tests, and observed database behavior when they disagree with general guidance. ## Reference index | Reference | Topics | | --- | --- | | [Compatibility and configuration](references/compatibility-and-configuration.md) | Runtime and build requirements, the yanked wheel, TOML configuration, path parsing, and path APIs | | [Autogenerate and rendering](references/autogenerate-and-rendering.md) | Indexes, constraints, operation rendering, comparators, filtering, and plugins | | [Operations and DDL](references/operations-and-ddl.md) | Conditional DDL, comments, inline keys and references, and offline version-table behavior | | [Revisions, CLI, and extensions](references/revisions-cli-and-extensions.md) | Revision paths and identifiers, head checks, merge splicing, command registration, and operation implementations | ## Upgrade triage ### Avoid the yanked 1.15.0 wheel Do not deploy Alembic 1.15.0. Its wheel omitted migration template files after the packaging move to PEP 621. Use 1.15.1 or later in that series. ### Enforce the applicable runtime floor - Alembic 1.15 requires Python 3.9+ and SQLAlchemy 1.4+. - Alembic 1.17 requires Python 3.10+. - Alembic 1.18 requires SQLAlchemy 1.4.23+. Check source-build environments separately: the 1.16 series raised its setuptools build requirement to 77.0.3. ### Update path parsing deliberately For new or updated INI files, set: ```ini [alembic] path_separator = os ``` `path_separator` replaces `version_path_separator`, applies to both `version_locations` and `prepend_sys_path`, and uses `os.pathsep` when set to `os`. An omitted setting preserves legacy splitting with a deprecation warning. ### Remove colons from custom revision identifiers Revision IDs cannot contain `:` because Alembic reserves it for revision-range syntax. Replace identifiers such as `REV:1` with an unambiguous form such as `REV_1` before creating or resolving revisions. ## Configuration quick reference ### Put source-generation settings in TOML `pyproject.toml` can hold source paths, generation settings, local paths, and post-write hooks. TOML lists are preferred for `version_locations` and `prepend_sys_path`, and `%(here)s` resolves from the TOML file's parent. Keep database connectivity and logging in `alembic.ini` or `env.py`. When `env.py` supplies both, the `pyproject` initialization template can operate without an INI file. ### Enable discovery for date-organized revision files `file_template` can contain directory separators and Alembic creates the directories. Always enable recursive version locations with a nested template: ```toml [tool.alembic] file_template = "%(year)d/%(month).2d/%(day).2d_%(rev)s_%(slug)s" recursive_version_locations = true ``` The key rule is that nested files require recursive discovery. ### Pass path objects only through public APIs Public command, configuration, and script path parameters accept `os.PathLike` objects. Their public path-returning accessors still return strings. Do not rely on private underscored APIs returning strings; the path refactor permits them to return `pathlib.Path` values. ## Migration safety quick reference ### Fail deployment checks when any head is missing Use the CLI: ```console alembic current --check-heads ``` Or call `command.current(config, check_heads=True)`. A database missing any head causes `DatabaseNotAtHead`; the CLI exits nonzero. ### Add backend-guarded DDL On supporting backends, use: ```python op.add_column("account", sa.Column("nickname", sa.String()), if_not_exists=True) op.drop_column("account", "legacy", if_exists=True) op.drop_constraint("uq_account_name", "account", type_="unique", if_exists=True) ``` The flags render `IF NOT EXISTS` or `IF EXISTS`, and custom autogenerate rewriters can attach the same flags to generated operations. ### Opt in to inline keys and references `Column(primary_key=True)` alone does not inline a primary key in `ADD COLUMN`. Pass `inline_primary_key=True` to `Operations.add_column()` when the backend supports that syntax and inline behavior is intended. Pass `inline_references=True` to render a column's `REFERENCES` clause within `ADD COLUMN` instead of emitting a separate constraint. See the DDL reference for supported backends and included foreign-key actions. ### Preserve the offline version table at `base` In `--sql` mode, `stamp base` and `downgrade base` retain `alembic_version`, matching online behavior. Alembic still creates the version table if absent. Do not expect these offline commands to emit `DROP TABLE alembic_version`. ## Autogenerate correctness quick reference ### Treat named CHECK comparison as name-only Named `CHECK` additions and removals are detected by default through the `alembic.autogenerate.checkconstraint_byname` plugin. Expression changes under an unchanged name do not produce a diff. Disable that comparator by excluding the plugin from `autogenerate_plugins` when name-based detection is unwanted. ### Select comparison plugins per environment Third-party `Plugin` implementations can register operations, implementations, and comparators. Select built-in and third-party comparison plugins with: ```python context.configure(autogenerate_plugins=[...]) ``` Existing extensions do not need plugin entry points, but new plugins can use `Plugin.add_autogenerate_comparator()` for automatic loading. ### Preserve finalized database names Rendered reflected constraint and index names use `Operations.f()` so active naming conventions do not transform final names twice. Keep wrappers such as: ```python op.drop_constraint(op.f("uq_account_name"), "account", type_="unique") ``` This is especially important for conventions using `%(constraint_name)s`. ### Account for filtered foreign-key placeholders Foreign keys whose targets were excluded by `include_name` or omitted from the reflected schemas no longer abort autogenerate. An `include_object` callback can receive placeholder target tables carrying only the table name, schema, and referenced columns. Do not assume those targets are fully reflected. ## Revision and extension quick reference ### Create a merge revision away from a head Use `alembic merge --splice rev_a rev_b`, or pass `splice=True` to `command.merge()`, when the merge revision must be based on non-head revisions. ### Ask for dependency-aware effective heads Call: ```python heads = script.get_heads(consider_depends_on=True) ``` This excludes nominal heads that another revision names through `depends_on`, matching the effective heads recorded after all upgrades. ### Extend public surfaces explicitly - Register application CLI commands with `CommandLine.register_command()`. - Replace an existing operation implementation with `Operations.implementation_for(..., replace=True)`. - When a rewriter represents a column rename, set `AlterColumnOp.modified_name`; Alembic does not infer the rename itself. ## Review workflow 1. Confirm the pinned Alembic, Python, SQLAlchemy, and backend versions. 2. Check the compatibility reference before changing packaging or configuration. 3. Review autogenerate output against naming conventions and filtered schemas. 4. Review backend-specific DDL flags and inline behavior before execution. 5. Validate the revision graph with head checks and dependency-aware lookup. 6. Test both online and `--sql` workflows when release tooling emits SQL. Open the indexed reference matching the task for the complete edge cases and version attributions; the quick reference intentionally focuses on the most failure-prone upgrade and migration paths.