dstandish commented on a change in pull request #21879:
URL: https://github.com/apache/airflow/pull/21879#discussion_r816475049
##########
File path: docs/apache-airflow/best-practices.rst
##########
@@ -577,3 +577,41 @@ For connection, use :envvar:`AIRFLOW_CONN_{CONN_ID}`.
conn_uri = conn.get_uri()
with mock.patch.dict("os.environ", AIRFLOW_CONN_MY_CONN=conn_uri):
assert "cat" == Connection.get("my_conn").login
+
+Metadata DB maintenance
+-----------------------
+
+Over time, the metadata database will increase its storage footprint as more
DAG and task runs and event logs accumulate.
+
+You can use the Airflow CLI to purge old data with command ``airflow db
clean``.
+
+See :ref:`db clean usage<cli-db-clean>` for more details.
+
+Upgrades and downgrades
+-----------------------
+
+Backup your database
+^^^^^^^^^^^^^^^^^^^^
+
+It's always a wise idea to backup the metadata database before undertaking any
operation modifying the database.
+
+Disabling the scheduler
+^^^^^^^^^^^^^^^^^^^^^^^
+
+You might consider disabling the Airflow cluster while you perform such
maintenance. One way to do so would be to set the param ``[scheduler] >
use_job_schedule`` to ``False`` and wait for any running DAGs to complete;
after this no new DAG runs will be created unless externally triggered.
+
+Another way to accomplish roughly the same thing is to use the ``dags pause``
command. You *must* keep track of the DAGs that are paused before you begin
this operation, otherwise when it comes time to unpause, you won't know which
ones should remain paused! So first run ``airflow dags list``, then store the
list of unpaused DAGs, and keep this list somewhere so that later you can
unpause only these.
+
+Upgrades
+^^^^^^^^
+
+Some database migrations can be time-consuming. If your metadata database is
very large, consider pruning some of the old data with the :ref:`db
clean<cli-db-clean>` command.
+
+If desired, you may apply each upgrade migration manually, one at a time. To
do so use the ``--revision-range`` option with ``db upgrade``. Do *not* skip
running the Alembic revision id update commands; this is how Airflow will know
where you are upgrading from or two the next time you need to. See
:doc:`/migrations-ref.rst` for a mapping between revision and version.
Review comment:
```suggestion
If desired, you may apply each upgrade migration manually, one at a time.
To do so use the ``--revision-range`` option with ``db upgrade``. Do *not*
skip running the Alembic revision id update commands; this is how Airflow will
know where you are upgrading from the next time you need to. See
:doc:`/migrations-ref.rst` for a mapping between revision and version.
```
--
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]
