How do I install the Migrating Airflow 2 To 3 skill?

Run npx skillmds@latest add tomevault-io/migrating-airflow-2-to-3-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Migrating Airflow 2 To 3 safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Migrating Airflow 2 To 3?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Migrating Airflow 2 To 3 free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Migrating Airflow 2 To 3?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Migrating Airflow 2 To 3 by tomevault-io

Name: Migrating Airflow 2 To 3
Author: tomevault-io

Migrating Airflow 2 To 3

Guide for migrating Apache Airflow 2.x projects to Airflow 3.x. Use when the user mentions Airflow 3 migration, upgrade, compatibility issues, breaking changes, or wants to modernize their Airflow codebase. Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

Airflow 2 to 3 Migration

This skill helps migrate Airflow 2.x DAG code to Airflow 3.x, focusing on code changes (imports, operators, hooks, context, API usage).

Important: Before migrating to Airflow 3, strongly recommend upgrading to Airflow 2.11 first, then to at least Airflow 3.0.11 (ideally 3.1).

Migration at a Glance

Run Ruff Airflow migration rules:
- ruff check --preview --select AIR --fix --unsafe-fixes .
Scan for remaining issues using a manual checklist:
- Direct metadata DB access
- Legacy imports
- Scheduling and context changes
- XCom pickling
- Datasets to assets
- REST API and auth
- Plugins and file paths
Plan changes per file and issue type
Implement changes incrementally and re-run Ruff
Explain changes and advise testing

Architecture and Metadata DB Access

Airflow 3 changes how components talk to the metadata database:

Workers no longer connect directly to the metadata DB
Task code runs via the Task Execution API
The DAG processor is separate from the scheduler

Direct ORM access now fails with:

RuntimeError: Direct database access via the ORM is not allowed in Airflow 3.x

Patterns to search for

provide_session, create_session, @provide_session
from airflow.settings import Session
from airflow.settings import engine
ORM usage with models: session.query(DagModel)...

Replacement: Airflow Python client

Add to requirements.txt:

apache-airflow-client==<your-airflow-runtime-version>

Example:

import os
import airflow_client.client
from airflow_client.client.api.dag_api import DAGApi

_HOST = os.getenv("AIRFLOW__API__BASE_URL", "https://<your-org>.astronomer.run/<deployment>/")
_TOKEN = os.getenv("DEPLOYMENT_API_TOKEN")

config = airflow_client.client.Configuration(host=_HOST, access_token=_TOKEN)
with airflow_client.client.ApiClient(config) as api_client:
    dag_api = DAGApi(api_client)
    dags = dag_api.get_dags(limit=10)

Ruff Airflow Migration Rules

AIR30 / AIR301 / AIR302: removed code and imports
AIR31 / AIR311 / AIR312: deprecated code and imports

Commands:

ruff check --preview --select AIR --fix --unsafe-fixes .
ruff check --preview --select AIR .

Key Import Changes

Airflow 2.x	Airflow 3
airflow.operators.dummy_operator.DummyOperator	airflow.providers.standard.operators.empty.EmptyOperator
airflow.operators.bash.BashOperator	airflow.providers.standard.operators.bash.BashOperator
airflow.operators.python.PythonOperator	airflow.providers.standard.operators.python.PythonOperator
airflow.decorators.dag	airflow.sdk.dag
airflow.decorators.task	airflow.sdk.task
airflow.datasets.Dataset	airflow.sdk.Asset

Context Key Changes

Removed Key	Replacement
execution_date	context["dag_run"].logical_date
tomorrow_ds / yesterday_ds	use macros.ds_add
triggering_dataset_events	triggering_asset_events
templates_dict	context["params"]

Default Behavior Changes

Setting	Airflow 2 Default	Airflow 3 Default
schedule	timedelta(days=1)	None
catchup	True	False

Resources

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: migrating-airflow-2-to-3-2description: Guide for migrating Apache Airflow 2.x projects to Airflow 3.x. Use when the user mentions Airflow 3 migration, upgrade, compatibility issues, breaking changes, or wants to modernize their Airflow codebase. Use when this capability is needed.---# Airflow 2 to 3 MigrationThis skill helps migrate Airflow 2.x DAG code to Airflow 3.x, focusing on code changes (imports, operators, hooks, context, API usage).Important: Before migrating to Airflow 3, strongly recommend upgrading to Airflow 2.11 first, then to at least Airflow 3.0.11 (ideally 3.1).## Migration at a Glance1. Run Ruff Airflow migration rules: - `ruff check --preview --select AIR --fix --unsafe-fixes .`2. Scan for remaining issues using a manual checklist: - Direct metadata DB access - Legacy imports - Scheduling and context changes - XCom pickling - Datasets to assets - REST API and auth - Plugins and file paths3. Plan changes per file and issue type4. Implement changes incrementally and re-run Ruff5. Explain changes and advise testing## Architecture and Metadata DB AccessAirflow 3 changes how components talk to the metadata database:- Workers no longer connect directly to the metadata DB- Task code runs via the Task Execution API- The DAG processor is separate from the schedulerDirect ORM access now fails with:```RuntimeError: Direct database access via the ORM is not allowed in Airflow 3.x```### Patterns to search for- `provide_session`, `create_session`, `@provide_session`- `from airflow.settings import Session`- `from airflow.settings import engine`- ORM usage with models: `session.query(DagModel)...`### Replacement: Airflow Python clientAdd to requirements.txt:```apache-airflow-client==<your-airflow-runtime-version>```Example:```pythonimport osimport airflow_client.clientfrom airflow_client.client.api.dag_api import DAGApi_HOST = os.getenv("AIRFLOW__API__BASE_URL", "https://<your-org>.astronomer.run/<deployment>/")_TOKEN = os.getenv("DEPLOYMENT_API_TOKEN")config = airflow_client.client.Configuration(host=_HOST, access_token=_TOKEN)with airflow_client.client.ApiClient(config) as api_client: dag_api = DAGApi(api_client) dags = dag_api.get_dags(limit=10)```## Ruff Airflow Migration Rules- AIR30 / AIR301 / AIR302: removed code and imports- AIR31 / AIR311 / AIR312: deprecated code and importsCommands:```bashruff check --preview --select AIR --fix --unsafe-fixes .ruff check --preview --select AIR .```## Key Import Changes| Airflow 2.x | Airflow 3 || --- | --- || airflow.operators.dummy_operator.DummyOperator | airflow.providers.standard.operators.empty.EmptyOperator || airflow.operators.bash.BashOperator | airflow.providers.standard.operators.bash.BashOperator || airflow.operators.python.PythonOperator | airflow.providers.standard.operators.python.PythonOperator || airflow.decorators.dag | airflow.sdk.dag || airflow.decorators.task | airflow.sdk.task || airflow.datasets.Dataset | airflow.sdk.Asset |## Context Key Changes| Removed Key | Replacement || --- | --- || execution_date | context["dag_run"].logical_date || tomorrow_ds / yesterday_ds | use macros.ds_add || triggering_dataset_events | triggering_asset_events || templates_dict | context["params"] |## Default Behavior Changes| Setting | Airflow 2 Default | Airflow 3 Default || --- | --- | --- || schedule | timedelta(days=1) | None || catchup | True | False |## Resources- https://www.astronomer.io/docs/astro/airflow3/upgrade-af3- https://airflow.apache.org/docs/apache-airflow/stable/release_notes.html---> Converted and distributed by [TomeVault](https://tomevault.io/claim/necatiarslan) — claim your Tome and manage your conversions.

Frequently asked questions