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.