This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch v3-1-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-1-test by this push:
new d7f3c3727ed [v3-1-test] Add testing details in db migration contrib
docs (#60053) (#60054)
d7f3c3727ed is described below
commit d7f3c3727ede6cccc440d29600797d16215e30ce
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Fri Jan 2 18:55:10 2026 +0100
[v3-1-test] Add testing details in db migration contrib docs (#60053)
(#60054)
(cherry picked from commit 9bdd6536e5d12f57aed81b80a4a1d0799784a667)
Co-authored-by: Zach <[email protected]>
---
contributing-docs/14_metadata_database_updates.rst | 23 +++++++++++++++++++---
1 file changed, 20 insertions(+), 3 deletions(-)
diff --git a/contributing-docs/14_metadata_database_updates.rst
b/contributing-docs/14_metadata_database_updates.rst
index f7af5e906ea..12ac4cdeeec 100644
--- a/contributing-docs/14_metadata_database_updates.rst
+++ b/contributing-docs/14_metadata_database_updates.rst
@@ -49,6 +49,13 @@ After your new migration file is run through prek hook it
will look like this:
This represents that your migration is the 1234th migration and expected for
release in Airflow version A.B.C.
+.. warning::
+
+ In rare cases, you may need to manually modify the migration logic of your
auto-generated migration script.
+ If you must make manual changes to your migration script, **you must ensure
you're not referencing any ORM classes
+ within your migration script**. Directly referring to an ORM class
definition within a migration script can lead to
+ unexpected and / or broken downgrade pathways in the future, `as described
here <https://github.com/apache/airflow/issues/59871>`_.
+
How to Resolve Conflicts When Rebasing
--------------------------------------
@@ -75,6 +82,16 @@ To resolve these conflicts:
3. Add the updated files to the staging area and continue with the rebase.
+Running migration CI tests locally
+----------------------------------
+
+The various CI migration tests are defined in
``.github/actions/migration_tests/action.yml``. These tests ensure the
+database upgrades and downgrades are still functional from the lowest
supported source migration version, to the latest version,
+and back down to the former. To run any of those CI tests on your machine, you
can:
+
+1. Copy the relevant command (specified by the ``run`` key for the relevant CI
job), and replace the environment variable references with their literal values
defined in the sibling ``env`` section.
+2. Run the command you created from step 1, troubleshooting errors as needed.
+
How to hook your application into Airflow's migration process
-------------------------------------------------------------
@@ -83,12 +100,12 @@ This feature is useful if you have a custom database
schema that you want to mig
This guide will show you how to hook your application into Airflow's migration
process.
Subclass the BaseDBManager
-==========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~
To hook your application into Airflow's migration process, you need to
subclass the ``BaseDBManager`` class from the
``airflow.utils.db_manager`` module. This class provides methods for running
Alembic migrations.
-Create Alembic migration scripts
-================================
+Create Alembic migration scripts for your application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At the root of your application, run "alembic init migrations" to create a new
migrations directory. Set the
``version_table`` variable in the ``env.py`` file to the name of the table
that stores the migration history. Specify this
version_table in the ``version_table`` argument of the alembic's
``context.configure`` method of the ``run_migration_online``
