This is an automated email from the ASF dual-hosted git repository.
Lee-W pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new e73c529bd89 Clarify the scope of db clean's `--tables` and DAG filter
options (#73242)
e73c529bd89 is described below
commit e73c529bd89bc5ef2642571c605865ca104f0083
Author: Kaxil Naik <[email protected]>
AuthorDate: Wed Sep 16 14:37:22 2026 +0100
Clarify the scope of db clean's `--tables` and DAG filter options (#73242)
---
airflow-core/docs/howto/usage-cli.rst | 28 +++++++++++++++++++++++++---
1 file changed, 25 insertions(+), 3 deletions(-)
diff --git a/airflow-core/docs/howto/usage-cli.rst
b/airflow-core/docs/howto/usage-cli.rst
index 21b37747e68..00647ff9f33 100644
--- a/airflow-core/docs/howto/usage-cli.rst
+++ b/airflow-core/docs/howto/usage-cli.rst
@@ -221,7 +221,21 @@ Purge history from metadata database
The ``db clean`` command works by deleting from each table the records older
than the provided ``--clean-before-timestamp``.
-You can optionally provide a list of tables to perform deletes on. If no list
of tables is supplied, all tables will be included.
+You can use the ``--dry-run`` option to print the tables that would be
cleaned, the configuration used for each, and the row counts, without deleting
anything.
+
+You can optionally provide a list of tables to perform deletes on with
``--tables``. If no list of tables is supplied, all tables will be included.
+
+.. note::
+
+ ``--tables`` sets where cleanup starts, not the full list of tables it
touches. Each table has a
+ configured list of dependent tables, and those are cleaned first, so that
their rows are archived
+ too. Asking for ``--tables trigger`` therefore also cleans ``task_instance``,
+ ``task_instance_history`` and ``xcom``, all of which the ``--dry-run``
output lists.
+
+ That list is maintained per table rather than derived from the schema, so it
does not cover every
+ foreign key. A table left off it can still lose rows to a cascading delete
when its parent is
+ cleaned, and those rows are neither listed in the dry run nor archived. See
+ `Beware cascading deletes`_ below.
.. note::
@@ -229,9 +243,17 @@ You can optionally provide a list of tables to perform
deletes on. If no list of
affects Dags waiting on a multi-asset condition, where a pending event can
be purged before the condition
is met, meaning the Dag will not be triggered by it.
-You can filter cleanup to specific DAGs using ``--dag-ids`` (comma-separated
list), or exclude specific DAGs using ``--exclude-dag-ids`` (comma-separated
list). These options allow you to target or avoid cleanup for particular DAGs.
+You can filter cleanup to specific DAGs using ``--dag-ids`` (comma-separated
list), or exclude specific DAGs using ``--exclude-dag-ids`` (comma-separated
list).
+
+.. warning::
+
+ Both options only reach tables whose cleanup configuration declares a DAG
column. Every other table is
+ cleaned whatever you pass, so ``--exclude-dag-ids`` does not preserve
everything connected to the DAGs
+ you name -- ``trigger``, ``callback`` and ``import_error`` declare none, for
instance, so the filters
+ never narrow them.
-You can use the ``--dry-run`` option to print the row counts in the primary
tables to be cleaned.
+ The ``--dry-run`` output shows a ``dag_id_column`` for each table it would
clean. Where that column is
+ ``None``, the DAG filters do not apply to that table.
By default, ``db clean`` will archive purged rows in tables of the form
``_airflow_deleted__<table>__<timestamp>``. If you don't want the data
preserved in this way, you may supply argument ``--skip-archive``.
