Re: [PR] Clarify db downgrade rollback limits [airflow]

["Eason09053360 (via GitHub)" <gi...@apache.org>]

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: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org