How to Use the Airflow 2 to 3 DAG Migration Prompt to Upgrade Without Losing DAGs

Airflow 3 is a real major release. Import paths moved, several context variables are gone, SubDAGs no longer exist, and task code can no longer reach into the metadata database. Teams that bump the image tag and hope for the best usually find out when DAGs disappear from the UI because of an import error. The Apache Airflow 2 to 3 DAG Migration Planner: Ruff AIR301 and AIR302 Scans, airflow.sdk Imports, schedule and logical_date Renames, Standard Provider Operators, No Direct Metadata DB Access, and a Staging Cutover Checklist prompt turns your actual DAG files into a phased plan with code diffs, commands, and a cutover checklist you can run in staging first.

What the prompt produces

1. A readiness gate that moves you to the latest 2.x release, clears deprecation warnings, backs up the metadata database, and checks provider support.
2. A Ruff scan plan using the AIR301 and AIR302 rules, with a review step before any autofix is accepted.
3. A rename table built from your files: airflow.sdk imports, Dataset to Asset, schedule_interval to schedule, and operators moved to the standard provider.
4. Template fixes that replace execution_date and its relatives with logical_date or the data interval values, shown before and after.
5. Behavior decisions per DAG, such as the new catchup default, SubDAGs rebuilt as TaskGroups, and removed SLA callbacks.
6. A rewrite plan for task code that used ORM sessions, moving it to the REST API, the SDK, or a maintenance job.
7. Deployment changes, including the api-server command, a separate DAG processor, config updates, and the database migration.
8. A staging cutover checklist with a rollback note that names your backup.

How to fill the inputs

CurrentVersion should include the exact Airflow and Python versions and how you install them. A constraints file and the official Docker image lead to different upgrade steps than a managed service.

DagInventory is the most important field. Paste the imports, DAG arguments, operators, and any Jinja templates. The prompt only rewrites code it can see, so a vague list like "about forty DAGs" gives you a vague plan.

Providers lists every provider package and version. Old provider pins are a common reason a DAG fails to import after the upgrade.

Deployment names your executor and the services you run, so the plan can tell you which containers change.

DbAccessInTasks is where you confess any task that opens settings.Session or queries DagRun directly. These are the tasks that break hardest in Airflow 3.

Reading the example output

The example migrates two DAGs from Airflow 2.9.3 running in docker compose with CeleryExecutor:

• The readiness phase comes before any code change. It asks for a week on the latest 2.x release so deprecation warnings show up in logs while the old version still works.
• Ruff runs twice. First as a plain check, then with a diff, so the engineer reads every proposed fix before applying it.
• The daily sales DAG gets a line by line diff. The import moves to airflow.sdk, BashOperator moves to the standard provider, days_ago becomes a fixed start date, and the execution_date template becomes a data interval value.
• The SubDAG becomes a TaskGroup, with a warning that task IDs gain a prefix, which can break alerts that match on the old IDs.
• The cleanup DAG is handled honestly. Since it deleted DagRun rows through a session, the plan suggests running the database clean command outside task code instead of forcing a workaround.
• The cutover checklist is concrete: zero import errors, one run per DAG, matching task counts, and a restore command if things go wrong.

Tips for better results

• Paste real code, even if it is ugly. The diffs are only as good as what you give the prompt.
• Run the scan on a branch and commit the Ruff fixes separately from your manual edits so reviews stay readable.
• Keep a list of task IDs that alerts or sensors depend on before you convert SubDAGs.
• Ask a follow up for one tricky DAG at a time if your inventory is large.

Mistakes to avoid

• Do not skip the database backup. A migration you cannot roll back is a gamble.
• Do not accept every autofix without reading it, especially around templates.
• Do not assume old provider versions work with Airflow 3. Check the provider changelog.
• Do not leave catchup implicit if a DAG depends on backfilling. State it on purpose.

Who it is for

Data engineers and platform teams who own an Airflow 2 deployment, analytics engineers who maintain a handful of DAGs and need a safe checklist, and consultants planning upgrades for several clients at once.

Related PromptDig links

Open the Apache Airflow 2 to 3 DAG Migration Planner: Ruff AIR301 and AIR302 Scans, airflow.sdk Imports, schedule and logical_date Renames, Standard Provider Operators, No Direct Metadata DB Access, and a Staging Cutover Checklist prompt and paste your DAG excerpts to get your own plan. For more developer prompts, Browse more prompts. If you have a migration prompt that saved you a weekend, Share a prompt.