.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

.. http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Upgrading FAB to a newer version

Before reading this, make sure you have read the Airflow Upgrade Guide for how to prepare for an upgrade: :doc:apache-airflow:installation/upgrading

Why you need to upgrade

The FAB provider is a separate package from Airflow and it is released independently. Starting from version 1.3.0, FAB can now run its own migrations if you are on Airflow 3. Newer FAB versions can contain database migrations, so you must run airflow fab-db migrate to migrate your database with the schema changes in the FAB version you are upgrading to. If FABDBManager is included in the [core] external_db_managers configuration, the migrations will be run automatically as part of the airflow db migrate command.

.. note:: If FAB auth manager is configured as auth manager in your environment, FABDBManager is automatically added in the [core] external_db_managers configuration.

How to upgrade

To upgrade the FAB provider, you need to install the new version of the package. You can do this using pip. After the installation, you can run the DB upgrade of the FAB provider by running the following command: airflow fab-db migrate. This command is only available if you are in Airflow 3.0.0 or newer.

The command takes the same options as airflow db migrate command, you can learn more about the command by running airflow fab-db migrate --help.

How to downgrade

If you need to downgrade the FAB provider, you can do this by running the downgrade command to the version you want to downgrade to, example airflow fab-db downgrade --to-version 1.2.0. Afterwards, install the new FAB provider version using pip.

There are other options to this command, check it out by running airflow fab-db downgrade -help.

Resetting the FAB database

If you need to reset the FAB database, you can do this by running the reset command, example airflow fab-db reset. This command will drop all tables in the FAB database and recreate them. This command is only available if you are in Airflow 3.0.0 or newer. There are other options to this command, check it out by running airflow fab-db reset --help.

Offline SQL migration scripts

If you want to run the upgrade script offline, you can use the -s or --show-sql-only flag to get the SQL statements that would be executed. You may also specify the starting FAB version with the --from-version flag and the ending FAB version with the -n or --to-version flag. This feature is supported in Postgres and MySQL.

Sample usage for Airflow version 2.7.0 or greater: airflow fab-db migrate -s --from-version "1.3.0" -n "1.4.0" airflow fab-db migrate --show-sql-only --from-version "1.3.0" --to-version "1.4.0"