Document that airflow db downgrade does not revert serialized row content

[krishn1301]

Related: #68317

What this documents

airflow db downgrade reverses schema migrations. It does not rewrite the contents of rows a newer Airflow already wrote. The upgrade guide currently says nothing about downgrading at all — the word doesn't appear in upgrading.rst — so users reasonably read a successful downgrade as "the database is now compatible with the old version". It isn't.

This adds a Downgrading to an earlier version section covering what the command reverts, what it doesn't, the symptom when it bites, and the fact that restoring a pre-upgrade backup is the only reliable rollback.

Verification

The interesting part is that Airflow's compatibility shim runs in exactly one direction, which is what turns a downgrade into a crash-loop.

3.1.8 — Trigger._decrypt_kwargs calls BaseSerialization directly, with nothing to fall back to:

from airflow.serialization.serialized_objects import BaseSerialization
...
return BaseSerialization.deserialize(decrypted_kwargs)

3.2.1 — the same method reads the Task SDK format first and falls back to the legacy one:

from airflow.sdk.serde import deserialize
...
try:
    result = deserialize(decrypted_kwargs)
    ...
except (ImportError, KeyError, AttributeError, TypeError):
    # Backward compatibility: fall back to BaseSerialization for old format
    from airflow.serialization.serialized_objects import BaseSerialization
    return BaseSerialization.deserialize(decrypted_kwargs)

So 3.2 reads 3.1's rows, and 3.1 cannot read 3.2's. The envelopes have no keys in common — shared/serialization/src/airflow_shared/serialization/__init__.py names them, and calls the legacy pair OLD_:

CLASSNAME = "__classname__"
VERSION   = "__version__"
DATA      = "__data__"
...
OLD_TYPE  = "__type"
OLD_DATA  = "__var"

BaseSerialization.deserialize subscripts that key unguarded at serialized_objects.py:652, which produces the KeyError: <Encoding.VAR: '__var'> from the issue:

var = encoded_var[Encoding.VAR]

One correction to the issue as filed

#68317 lists dag_run.conf and "related serialized columns" as affected by the 3.2 serde move. I don't think that part holds. ExtendedJSON — the TypeDecorator behind dag_run.conf, taskmap, taskinstance and friends, and the frame that appears in the reporter's traceback — still uses BaseSerialization in both versions:

# airflow-core/src/airflow/utils/sqlalchemy.py, identical in 3.1.8 and 3.2.1
def process_result_value(self, value, dialect):
    from airflow.serialization.serialized_objects import BaseSerialization
    ...
    return BaseSerialization.deserialize(value)

The serde change is confined to call sites that explicitly import airflow.sdk.serde, and trigger.kwargs is the one on this path. I've scoped the docs to trigger kwargs rather than repeating the broader claim. That does leave the reporter's _schedule_all_dag_runs frame unexplained, so if a committer knows of a second 3.2 write path into an ExtendedJSON column I'm happy to widen the section.

Deliberately not changed

The airflow db downgrade help text and the interactive prompt both already say "schema" — accurate, but easy to skim past:

Warning: About to reverse schema migrations for the airflow metastore.

I kept this PR to documentation. If you'd like a pointer to the new section added to cli_config.py's description, say the word and I'll add it here.

Newsfragment

Happy to add {pr}.doc.rst under airflow-core/newsfragments once this has a number, since the CI check validates the filename against it. Let me know if you want one for a docs-only change.

---

^ Add meaningful description above
Read the Pull Request Guidelines for more information.

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide
Here are some useful points:

• Pay attention to the quality of your code (ruff, mypy and type annotations). Our prek-hooks will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example Dag that shows how users should use it.
• Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
• Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits.
  Apache Airflow is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@airflow.apache.org
  Slack: https://s.apache.org/airflow-slack