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

1.15.1

1.15.1

Released: March 4, 2025

bug

• [bug] [installation] Fixed an issue in the new PEP 621 pyproject.toml layout that
  prevented Alembic's template files from being included in the .whl file
  in the distribution.

  References: #1616

1.15.0

1.15.0

Released: March 4, 2025

changed

• [changed] [general] Support for Python 3.8 is dropped as of Alembic 1.15.0; this version is
  now EOL so Python 3.9 or higher is required for Alembic 1.15.

• [changed] [general] Support for SQLAlchemy 1.3, which was EOL as of 2021, is now dropped from
  Alembic as of version 1.15.0. SQLAlchemy version 1.4 or greater is
  required for use with Alembic 1.15.0.

• [changed] [general] Installation has been converted to use PEP 621, e.g. pyproject.toml.

usecase

• [usecase] [autogenerate] Index autogenerate will now render labels for expressions
  that use them. This is useful when applying operator classes
  in PostgreSQL that can be keyed on the label name.

  References: #1603

• [usecase] [autogenerate] Add revision context to AutogenerateDiffsDetected so that command can be
  wrapped and diffs may be output in a different format. Pull request
  courtesy Louis-Amaury Chaib (@lachaib).

  References: #1597

bug

• [bug] [environment] Added a basic docstring to the migration template files so that the
  upgrade/downgrade methods pass the D103 linter check which requires a
  docstring for public functions. Pull request courtesy Peter Cock.

  References: #1567

• [bug] [autogenerate] Fixed autogenerate rendering bug where the deferrable element of
  UniqueConstraint, a bool, were being stringified rather than repr'ed
  when generating Python code.

  References: #1613

1.14.1

1.14.1

Released: January 19, 2025

usecase

• [usecase] [sqlite] Modified SQLite's dialect to render "ALTER TABLE RENAME COLUMN" when
  Operations.alter_column() is used with a straight rename, supporting
  SQLite's recently added column rename feature.

  References: #1576

bug

• [bug] [environment] Added tzdata to tz extras, which is required on some platforms such as
  Windows. Pull request courtesy Danipulok.

  References: #1556

• [bug] [autogenerate] Fixed bug where autogen render of a "variant" type would fail to catch the
  variants if the leading type were a dialect-specific type, rather than a
  generic type.

  References: #1585