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

1.14.0

1.14.0

Released: November 4, 2024

usecase

• [usecase] [runtime] Added a new hook to the DefaultImpl
DefaultImpl.version_table_impl(). This allows third party dialects
  to define the exact structure of the alembic_version table, to include use
  cases where the table requires special directives and/or additional columns
  so that it may function correctly on a particular backend. This is not
  intended as a user-expansion hook, only a dialect implementation hook to
  produce a working alembic_version table. Pull request courtesy Maciek
  Bryński.

  References: #1560

1.13.3

1.13.3

Released: September 23, 2024

usecase

• [usecase] [autogenerate] Render if_exists and if_not_exists parameters in
  CreateTableOp, CreateIndexOp, DropTableOp and
  DropIndexOp in an autogenerate context. While Alembic does not
  set these parameters during an autogenerate run, they can be enabled using
  a custom Rewriter in the env.py file, where they will now be
  part of the rendered Python code in revision files. Pull request courtesy
  of Louis-Amaury Chaib (@lachaib).

• [usecase] [environment] Enhance version_locations parsing to handle paths containing newlines.

  References: #1509

• [usecase] [operations] Added support for Operations.create_table.if_not_exists and
  Operations.drop_table.if_exists, adding similar functionality
  to render IF [NOT] EXISTS for table operations in a similar way as with
  indexes. Pull request courtesy Aaron Griffin.

  References: #1520

misc

• [change] [general] The pin for setuptools<69.3 in pyproject.toml has been removed.
  This pin was to prevent a sudden change to PEP 625 in setuptools from
  taking place which changes the file name of SQLAlchemy's source
  distribution on pypi to be an all lower case name, and the change was
  extended to all SQLAlchemy projects to prevent any further surprises.
  However, the presence of this pin is now holding back environments that
  otherwise want to use a newer setuptools, so we've decided to move forward
  with this change, with the assumption that build environments will have
  largely accommodated the setuptools change by now.

1.13.2

1.13.2

Released: June 26, 2024

usecase

• [usecase] [autogenerate] Improve computed column compare function to support multi-line expressions.
  Pull request courtesy of Georg Wicke-Arndt.

  References: #1391

bug

• [bug] [commands] Fixed bug in alembic command stdout where long messages were not properly
  wrapping at the terminal width. Pull request courtesy Saif Hakim.

  References: #1384

• [bug] [execution] Fixed internal issue where Alembic would call connection.execute()
  sending an empty tuple to indicate "no params". In SQLAlchemy 2.1 this
  case will be deprecated as "empty sequence" is ambiguous as to its intent.

  References: #1394

• [bug] [tests] Fixes to support pytest 8.1 for the test suite.

  References: #1435

• [bug] [autogenerate] [postgresql] Fixed the detection of serial column in autogenerate with tables
  not under default schema on PostgreSQL

  References: #1479

1.13.1

1.13.1

Released: December 20, 2023

bug

• [bug] [autogenerate] Fixed Rewriter so that more than two instances could be chained
  together correctly, also allowing multiple process_revision_directives
  callables to be chained. Pull request courtesy zrotceh.

  References: #1337

• [bug] [environment] Fixed issue where the method EnvironmentContext.get_x_argument()
  using the EnvironmentContext.get_x_argument.as_dictionary
  parameter would fail if an argument key were passed on the command line as
  a name alone, that is, without an equal sign = or a value. Behavior is
  repaired where this condition is detected and will return a blank string
  for the given key, consistent with the behavior where the = sign is
  present and no value. Pull request courtesy Iuri de Silvio.

  References: #1369

• [bug] [autogenerate] Fixed issue where the "unique" flag of an Index would not be maintained
  when generating downgrade migrations. Pull request courtesy Iuri de
  Silvio.

  References: #1370

• [bug] [versioning] Fixed bug in versioning model where a downgrade across a revision with two
  down revisions with one down revision depending on the other, would produce
  an erroneous state in the alembic_version table, making upgrades impossible
  without manually repairing the table. Thanks much to Saif Hakim for
  the great work on this.

  References: #1373

• [bug] [typing] Updated pep-484 typing to pass mypy "strict" mode, however including
  per-module qualifications for specific typing elements not yet complete.
  This allows us to catch specific typing issues that have been ongoing
  such as import symbols not properly exported.

  References: #1377