1.18.1

Released: January 14, 2026

bug

• [bug] [autogenerate] Fixed issue in new plugin system where the configured logger was not
  correctly using the __name__ token to identify the logger.

  References: #1779

• [bug] [operations] Revised the change regarding SQLAlchemy 2.1 and deprecation warnings
  related to isolate_from_table=True. Further developments in release 2.1
  have revised how this parameter will be modified.

1.18.0

Released: January 9, 2026

feature

• [feature] [operations] When alembic is run in "verbose" mode, alembic now logs a message to
  indicate from which file is used to load the configuration.

  References: #1737

• [feature] [autogenerate] Autogenerate reflection sweeps now use the "bulk" inspector methods
  introduced in SQLAlchemy 2.0, which for selected dialects including
  PostgreSQL and Oracle use batched queries to reflect whole collections of
  tables using O(1) queries rather than O(N).

  References: #1771

• [feature] [autogenerate] Release 1.18.0 introduces a plugin system that allows for automatic
  loading of third-party extensions as well as configurable autogenerate
  compare functionality on a per-environment basis.

  The Plugin class provides a common interface for extensions that
  register handlers among Alembic's existing extension points such as
  Operations.register_operation() and
  Operations.implementation_for(). A new interface for registering
  autogenerate comparison handlers,
  Plugin.add_autogenerate_comparator(), provides for autogenerate
  compare functionality that may be custom-configured on a per-environment
  basis using the new
  EnvironmentContext.configure.autogenerate_plugins parameter.

  The change does not impact well known Alembic add-ons such as
  alembic-utils, which continue to work as before; however, such add-ons
  have the option to provide plugin entrypoints going forward.

  As part of this change, Alembic's autogenerate compare functionality is
  reorganized into a series of internal plugins under the
  alembic.autogenerate namespace, which may be individually or
  collectively identified for inclusion and/or exclusion within the
  EnvironmentContext.configure() call using a new parameter
  EnvironmentContext.configure.autogenerate_plugins. This
  parameter is also where third party comparison plugins may also be
  indicated.

  See alembic.plugins.toplevel for complete documentation on
  the new Plugin class as well as autogenerate-specific usage
  instructions.

usecase

• [usecase] [environment] The file_template configuration option now supports directory paths,
  allowing migration files to be organized into subdirectories. When using
  directory separators in file_template (e.g.,
  %(year)d/%(month).2d/%(day).2d_%(rev)s_%(slug)s), Alembic will
  automatically create the necessary directory structure. The
  recursive_version_locations setting must be set to true when using
  this feature in order for the revision files to be located for subsequent
  commands.

  References: #1774

• [usecase] Avoid deprecation warning in add/drop constraint added in SQLAlchemy 2.1.
  Ensure that alembic is compatible with the changes added in
  sqlalchemy/sqlalchemy#13006
  by explicitly setting isolate_from_table=True when running with
  SQLAlchemy 2.1 or greater.

bug

• [bug] [postgresql] Fixed issue where PostgreSQL sequence defaults on non-primary key columns
  were incorrectly detected as changed on every autogenerate run. Server
  default comparison logic is adjusted to filter out the ::regclass
  expression added by the server which interferes with the comparison.

  References: #1507

• [bug] [mssql] Implemented DDL for column comment add/update/delete when using the
  Operations.alter_column.comment parameter with
  Operations.alter_column() on Microsoft SQL Server. Previously,
  these functions were not implemented for SQL Server and would raise
  UnsupportedCompilationError.

  References: #1755

1.17.2

Released: November 14, 2025

feature

• [feature] [operations] Added Operations.implementation_for.replace parameter to
  Operations.implementation_for(), allowing replacement of existing
  operation implementations. This allows for existing operations such as
  CreateTableOp to be extended directly. Pull request courtesy
  justanothercatgirl.

  References: #1750

bug

• [bug] [mssql] Fixed issue in SQL Server dialect where the DROP that's automatically
  emitted for existing default constraints during an ALTER COLUMN needs to
  take place before not just the modification of the column's default, but
  also before the column's type is changed.

  References: #1744

1.17.1

Released: October 28, 2025

usecase

• [usecase] [commands] Added command.current.check_heads parameter to
  command.current() command, available from the command line via the
  --check-heads option to alembic current. This tests if all head
  revisions are applied to the database and raises DatabaseNotAtHead
  (or from the command line, exits with a non-zero exit code) if this is not
  the case. The parameter operates equvialently to the cookbook recipe
  cookbook_check_heads. Pull request courtesy Stefan Scherfke.

  References: #1705

bug

• [bug] [commands] Disallow ':' character in custom revision identifiers. Previously, using a
  colon in a revision ID (e.g., 'REV:1') would create the revision, however
  revisions with colons in them are not correctly interpreted by other
  commands, as it overlaps with the revision range syntax. Pull request
  courtesy Kim Wooseok with original implementation by Hrushikesh Patil.

  References: #1540

1.17.0

Released: October 11, 2025

• [change] [tests] The top-level test runner has been changed to use nox, adding a
  noxfile.py as well as some included modules. The tox.ini file
  remains in place so that tox runs will continue to function in the near
  term, however it will be eventually removed and improvements and
  maintenance going forward will be only towards noxfile.py.

• [change] [general] The minimum Python version is now 3.10, as Python 3.9 is EOL.

1.16.5

Released: August 27, 2025

bug

• [bug] [mysql] Fixed Python-side autogenerate rendering of index expressions in MySQL
  dialect by aligning it with SQLAlchemy's MySQL index expression rules. Pull
  request courtesy david-fed.

  References: #1492

• [bug] [config] Fixed issue where new pyproject.toml config would fail to parse the integer
  value used for the truncate_slug_length parameter. Pull request
  courtesy Luís Henrique Allebrandt Schunemann.

  References: #1709

1.16.4

Released: July 10, 2025

bug

• [bug] [config] Fixed issue in new pyproject.toml support where boolean values, such as
  those used for the recursive_version_locations and sourceless
  configuration parameters, would not be accepted.

  References: #1694

1.16.3

Released: July 8, 2025

usecase

• [usecase] [commands] Added new pyproject_async template, combining the new pyproject
  template with the async template. Pull request courtesy Alc-Alc.

  References: #1683

• [usecase] [autogenerate] Add "module" post-write hook. This hook type is almost identical to the
  console_scripts hook, except it's running python -m black instead of
  using black's console_script. It is mainly useful for tools without
  console scripts (e.g. ruff), but has semantics closer to the
  console_scripts hook in that it finds the ruff module available to the
  running interpreter instead of finding an executable by path. Pull request
  courtesy Frazer McLean.

  References: #1686

bug

• [bug] [autogenerate] Fixed the rendering of server_default=FetchedValue() to ensure it is
  preceded by the sa. prefix in the migration script. Pull request
  courtesy david-fed.

  References: #1633

• [bug] [autogenerate] Fixed autogenerate rendering bug which failed to render foreign key
  constraints local to a CreateTableOp object if it did not refer
  to a MetaData collection via a private constructor argument that would
  not ordinarily be passed in user-defined rewriter recipes, including ones
  in the Alembic cookbook section of the docs.

  References: #1692

1.16.2

Released: June 16, 2025

bug

• [bug] [autogenerate] Fixed issue where dialect-specific keyword arguments in dialect_kwargs
  were not rendered when rendering the Operations.create_foreign_key()
  operation. This prevented dialect-specific keywords from being rendered
  using custom Rewriter recipes that modify
  ops.CreateForeignKeyOp, similar to other issues such as
  #1635. Pull request courtesy Justin Malin.

  References: #1671

• [bug] [command] Fixed rendering of pyproject.toml to include two newlines when
  appending content to an existing file. Pull request courtesy Jonathan
  Vanasco.

  References: #1679

1.16.1

Released: May 21, 2025

bug

• [bug] [command] Fixed regression caused by the pathlib refactoring that removed the use
  of Config.get_template_directory() as the canonical source of
  templates; the method is still present however it no longer would be
  consulted for a custom config subclass, as was the case with flask-migrate.

  References: #1660

• [bug] [command] Fixed regression caused by the pathlib refactoring where the "missing
  template" error message failed to render the name of the template that
  could not be found.

  References: #1659