●Change8

rel_1_16_0

Breaking Changes
📦 alembicView on GitHub →
⚠ 1 breaking✨ 6 features🐛 4 fixes⚡ 2 deprecations🔧 8 symbols

Summary

Alembic 1.16.0 adds PEP 621 configuration, a new CLI registration API, enhanced path handling, and several operation flags, while fixing autogenerate and deprecation issues.

⚠️ Breaking Changes

  • Public API functions that previously returned directory paths as strings (e.g., private helpers) may now return pathlib.Path objects, which can break code that assumes a string.

Migration Steps

  1. If your code relies on private API functions returning string paths, update it to accept `os.PathLike` objects or convert the returned `Path` to `str`.
  2. Replace any usage of the deprecated `utcnow()` function with `now(UTC)`.
  3. Update configuration files to use `path_separator` instead of `version_path_separator`; remove the old option to avoid deprecation warnings.
  4. Ensure your build environment uses setuptools version 77.0.3 or newer due to the updated `pyproject.toml`.

✨ New Features

  • Added optional PEP 621 support allowing Alembic configuration via `pyproject.toml` with a new `pyproject` init template.
  • Introduced `CommandLine.register_command()` method for registering custom CLI commands.
  • Added new `path_separator` configuration option to replace `version_path_separator` and handle OS‑dependent path splitting for both `version_locations` and `prepend_sys_path`.
  • Added `Operations.add_column.if_not_exists` to render `ADD COLUMN IF NOT EXISTS`.
  • Added `Operations.drop_column.if_exists` to render `DROP COLUMN IF EXISTS`.
  • Added `Operations.drop_constraint.if_exists` to render `DROP CONSTRAINT IF EXISTS`.

🐛 Bug Fixes

  • Updated Alembic's own `pyproject.toml` to use PEP 639 license configuration, bumping setuptools requirement to 77.0.3 and removing deprecation warnings.
  • Replaced deprecated `utcnow()` usage with `now(UTC)` to stop warning generation.
  • Fixed `Operations.execute()` autogenerate rendering to respect `configure.alembic_module_prefix` instead of hard‑coding `op.`.
  • Corrected autogenerate to apply `Operations.f()` to reflected constraint and index names, preventing double‑processing of naming conventions.

🔧 Affected Symbols

CommandLine.register_commandConfig.path_separatorOperations.add_column.if_not_existsOperations.drop_column.if_existsOperations.drop_constraint.if_existsScriptDirectory.dirConfig.config_file_nameprivate path helper functions (e.g., _some_path_func)

⚡ Deprecations

  • `version_path_separator` is deprecated in favor of the new `path_separator` option; use `path_separator` to avoid deprecation warnings.
  • The `utcnow()` function is deprecated and has been replaced by `now(UTC)`.