1.17.2

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

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

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

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

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

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

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

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

1.16.0

1.16.0

Released: May 21, 2025

feature

• [feature] [environment] Added optional PEP 621 support to Alembic, allowing all source code
  related configuration (e.g. local file paths, post write hook
  configurations, etc) to be configured in the project's pyproject.toml
  file. A new init template pyproject is added which illustrates a
  basic PEP 621 setup.

  Besides being better integrated with a Python project's existing source
  code configuration, the TOML format allows for more flexible structures,
  allowing configuration items like version_locations and
  prepend_sys_path to be configured as lists of path strings without the
  need for path separator characters used by ConfigParser format. The
  feature continues to support the %(here)s token which can substitute
  the absolute parent directory of the pyproject.toml file when
  consumed.

  The PEP 621 feature supports configuration values that are relevant to
  source code organization and generation only; it does not accommodate
  configuration of database connectivity or logging, which remain under the
  category of "deployment" configuration and continue to be part of
  alembic.ini, or whatever configurational method is established by the
  env.py file. Using the combination of pyproject.toml for source
  code configuration along with a custom database/logging configuration
  method established in env.py will allow the alembic.ini file to be
  omitted altogether.

  References: #1082

• [feature] [commands] Added new CommandLine.register_command() method to
  CommandLine, intended to facilitate adding custom commands to
  Alembic's command line tool with minimal code required; previously this
  logic was embedded internally and was not publicly accessible. A new
  recipe demonstrating this use is added. Pull request courtesy Mikhail
  Bulash.

  References: #1610

usecase

• [usecase] [environment] Added new option to the ConfigParser (e.g. alembic.ini) configuration
  path_separator, which supersedes the existing version_path_separator
  option. path_separator specifies the path separator character that
  will be recognized for both the version_locations option as well
  as the prepend_sys_path option, defaulting to os which indicates
  that the value of os.pathsep should be used.

  The new attribute applies necessary os-dependent path splitting to the
  prepend_sys_path option so that windows paths which contain drive
  letters with colons are not inadvertently split, whereas previously
  os-dependent path splitting were only available for the version_locations option.

  Existing installations that don't indicate path_separator
  will continue to use the older behavior, where version_path_separator
  may be configured for version_locations, and prepend_sys_path
  continues to be split on spaces/commas/colons. A deprecation warning
  is emitted for these fallback scenarios.

  When using the new pyproject.toml configuration detailed at
  using_pep_621, the whole issue of "path separators" is sidestepped
  and parameters like path_separator are unnecessary, as the TOML based
  configuration configures version locations and sys path elements as
  lists.

  Pull request courtesy Mike Werezak.

  References: #1330

• [usecase] [operations] Added Operations.add_column.if_not_exists and
  Operations.drop_column.if_exists to render IF [NOT] EXISTS
  for ADD COLUMN and DROP COLUMN operations, a feature available on
  some database backends such as PostgreSQL, MariaDB, as well as third party
  backends. The parameters also support autogenerate rendering allowing them
  to be added to autogenerate scripts via a custom Rewriter. Pull
  request courtesy of Louis-Amaury Chaib (@lachaib).

  References: #1626

• [usecase] [operations] Added Operations.drop_constraint.if_exists parameter to
  Operations.drop_constraint() which will render DROP CONSTRAINT IF EXISTS. The parameter also supports autogenerate rendering allowing it to
  be added to autogenerate scripts via a custom Rewriter. Pull
  request courtesy Aaron Griffin.

  References: #1650

bug

• [bug] [general] The pyproject.toml file used by the Alembic project itself for its
  Python package configuration has been amended to use the updated PEP 639
  configuration for license, which eliminates loud deprecation warnings when
  building the package. Note this necessarily bumps setuptools build
  requirement to 77.0.3.

  References: #1637

• [bug] [environment] Fixed issue where use of deprecated utcnow() function would generate
  warnings. Has been replaced with now(UTC). Pull request courtesy
  Jens Tröger.

  References: #1643

• [bug] [autogenerate] The Operations.execute() operation when rendered in autogenerate
  (which would necessarily be only when using a custom writer that embeds
  ExecuteSQLOp) now correctly takes into account the value
  configured in configure.alembic_module_prefix when rendering
  the operation with its prefixing namespace; previously this was hardcoded
  to op.. Pull request courtesy Avery Fischer.

  References: #1656

• [bug] [autogenerate] The autogenerate process will now apply the Operations.f() modifier
  to the names of all constraints and indexes that are reflected from the
  target database when generating migrations, which has the effect that these
  names will not have any subsequent naming conventions applied to them when
  the migration operations proceed. As reflected objects already include the
  exact name that's present in the database, these names should not be
  modified. The fix repairs the issue when using custom naming conventions
  which feature the %(constraint_name)s token would cause names to be
  double-processed, leading to errors in migration runs.

  References: #264

refactored

• [refactored] [environment] The command, config and script modules now rely on pathlib.Path for
  internal path manipulations, instead of os.path() operations. This
  has some impact on both public and private (i.e. underscored) API functions:

  -   Public API functions that accept parameters indicating file and directory
      paths as strings will continue to do so, but now will also accept
      `os.PathLike` objects as well.
  
  -   Public API functions and accessors that return directory paths as strings
      such as `ScriptDirectory.dir`, `Config.config_file_name`
      will continue to do so.
  
  -   Private API functions and accessors, i.e. all those that are prefixed
      with an underscore, that previously returned directory paths as
      strings may now return a Path object instead.
  

1.15.2

1.15.2

Released: March 28, 2025

bug

• [bug] [autogenerate] Fixed issue where the "modified_name" of AlterColumnOp would not
  be considered when rendering op directives for autogenerate. While
  autogenerate cannot detect changes in column name, this would nonetheless
  impact approaches that made use of this attribute in rewriter recipes. Pull
  request courtesy lenvk.

  References: #1635