krishn1301 opened a new pull request, #71984:
URL: https://github.com/apache/airflow/pull/71984
<!--
Thank you for contributing! Please make sure that your code changes
are covered with tests. And in case of new features or big changes
remember to adjust the documentation.
-->
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:
```python
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:
```python
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_`:
```python
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:
```python
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:
```python
# 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.
---
<!-- Please keep an empty line above the dashes. -->
^ Add meaningful description above
Read the [Pull Request
Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)
for more information.
--
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]
