Eason09053360 commented on code in PR #69645:
URL: https://github.com/apache/airflow/pull/69645#discussion_r4112253372
##########
airflow-core/docs/howto/usage-cli.rst:
##########
@@ -323,6 +323,13 @@ Downgrading Airflow
You can downgrade to a particular Airflow version with the ``db downgrade``
command. Alternatively you may provide an Alembic revision id to downgrade to.
+.. warning::
+
+ ``db downgrade`` only reverts schema changes tracked by Alembic. It does
not rewrite metadata rows
+ that were already written by the newer Airflow version into an older
serialization format. If the
+ newer version has already run against the database, restoring a metadata
DB backup taken before the
+ upgrade is the only clean rollback path.
Review Comment:
"If the newer version has already run against the database" covers almost
every real downgrade, so this reads as "`db downgrade` is never clean". It
might also conflicts with the `dags reserialize` note at the end of this
section. Making it conditional keeps both true, and naming the error helps
people searching for it.
```suggestion
``db downgrade`` runs the Alembic downgrade migrations. They revert
schema changes, but convert only
the data they were written to convert. Anything else the newer Airflow
version wrote in a format the
older version cannot read stays as it is. For example, Airflow 3.1
cannot read trigger kwargs written
by Airflow 3.2 and fails with ``KeyError: '__var'``. In such cases,
restoring a metadata DB backup
taken before the upgrade is the only clean rollback path.
```
##########
airflow-core/docs/installation/upgrading.rst:
##########
@@ -42,6 +42,11 @@ migration might be the only easy way out. This can for
example be caused by a br
network connection between your CLI and the database while the migration
happens, so taking
a backup is an important precaution to avoid problems like this.
+Backups are also the only clean rollback path when a newer Airflow version has
already written
+metadata rows in a format that an older version cannot read. ``airflow db
downgrade`` only
+reverts Alembic schema migrations; it does not rewrite existing metadata row
content back to an
+older serialization format.
Review Comment:
Same correction here, plus the concrete 3.2 → 3.1 case from the issue.
```suggestion
Backups are also the only clean rollback path when a newer Airflow version
has already written
metadata in a format that an older version cannot read. ``airflow db
downgrade`` reverts schema
changes, but its downgrade migrations convert only the data they were
written to convert. For
example, Airflow 3.1 cannot read trigger kwargs written by Airflow 3.2, even
after
``airflow db downgrade`` succeeds.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
