Why a 3.1 to 3.2 Airflow upgrade needs its own plan
If your team runs self-hosted Airflow 3.1, the decision is when to move to 3.2, and the answer depends on what your DAGs, images and database tooling depend on today. Airflow 3.2.0, released on April 7, 2026, adds asset partitioning, multi-team deployments, synchronous Deadline Alert callbacks, gunicorn support for the API server and Python 3.14 support. It also carries removals that can break working code: methods on TaskInstance and PriorityWeightStrategy are gone, the --conn-id option was removed from airflow connections list, the MySQL client is no longer shipped in container images, and the release moves Airflow to SQLAlchemy 2.0. Those changes are not cosmetic, so a feature-driven upgrade still needs a removal review first.
The general path from the Airflow 3 upgrade guide still applies: move to the latest patch on your current line, check DAG code for breaking changes, and back up the metadata database before you change anything. Start by listing every custom operator, sensor, plugin and deployment image that calls the removed methods or depends on the MySQL client, and confirm which SQLAlchemy usage lives in your own code or in provider packages. Ask your image owner whether any build step installs mysqlclient or relies on the mysql command inside the container. The Apache Airflow release notes list each change by version, and they are the reference to check against your repository.
Airflow 3.3.2 is the current patch release, and the move from 3.2 to 3.3 is covered on its own page, so do not treat this step as the final target without reviewing it. Plan 3.2 as a stepping stone only if your change window, provider versions and staging environment support it. Confirm with your platform team whether a single upgrade to 3.2 is acceptable for your release calendar, and record the rollback plan for the metadata database before the first staging run.
Which 3.2.0 changes affect your deployment and what to do
This table lists each Airflow 3.2.0 change from the release notes, who is most likely to be affected and the first action to take. Read the rows that match your DAG code, database, container images and API server setup, then confirm the rest against the full release notes before you plan the upgrade window.
| Change | Who is affected | Action needed |
|---|---|---|
| SQLAlchemy 2.0 upgrade | Teams with custom hooks, plugins or task code that run their own SQLAlchemy queries against the Airflow metadata database | Search custom code for SQLAlchemy 1.x patterns, test each query path in staging and confirm any pinned SQLAlchemy versions in your images |
| Removed methods on TaskInstance | DAG authors and plugin developers who call TaskInstance methods removed in 3.2.0 | Check the release notes for the removed method names, replace calls in your code and run unit tests on affected tasks |
| Removed methods on PriorityWeightStrategy | Teams with custom priority weight strategies configured for scheduling | Review any custom strategy class against the release notes and update overridden methods before upgrading |
| Removed --conn-id option on airflow connections list | Operators and CI scripts that list connections with the --conn-id flag | Update scripts to the supported listing syntax in the 3.2.0 CLI and confirm the output in a staging environment |
| MySQL client removed from container images | Teams that build on the official images and rely on the MySQL client binary inside tasks or sidecars | Add the MySQL client to your own image layer if tasks need it, then rebuild and test images before rollout |
| Python 3.14 support added | Teams planning a Python upgrade for schedulers, workers or images | Confirm that providers and custom dependencies install on Python 3.14 before changing the base image; keep the current Python version until tests pass |
| Multi-team deployments | Organizations sharing one Airflow environment across several teams | Decide team boundaries and access rules before enabling the feature, and review your security model with your platform team |
| Asset partitioning | Teams using assets to drive data-aware scheduling | Review asset definitions and downstream schedules to decide whether partitioning fits your pipelines; leave existing assets unchanged until tested |
| Synchronous Deadline Alert callbacks | Teams that use Deadline Alerts to notify on late runs | Check callback code for long-running work, since callbacks now run synchronously, and test alert delivery in staging |
| Gunicorn for the API server | Teams running the API server directly in containers, VMs or behind a load balancer | Review your start command and worker settings, and test zero-downtime worker recycling in a staging release before production |
How the removed TaskInstance and priority methods break DAG code
Removed methods on TaskInstance and PriorityWeightStrategy only break your environment where custom code calls them. Stock DAG code written against the public operators usually will not touch these methods, so the failures tend to appear in places nobody reviews during routine DAG changes: plugins, custom priority weight strategies, shared utility libraries and operator subclasses. Depending on where the call sits, the failure can surface when the DAG file is parsed by the DAG processor or only when a task runs, which means a clean parse does not prove the code is safe. Build an inventory of every module that imports Airflow internals and every class that subclasses TaskInstance or PriorityWeightStrategy before you schedule the upgrade.
Search the repository and any internal packages for calls to the methods named in the Airflow 3.2.0 release notes. Start with the Apache Airflow release notes and copy the exact removed method names into your search list, rather than relying on memory or a secondary summary. Include dags/, plugins/, any include/ or shared package directories, and the repositories that build your worker images. Grep results will be noisy, so have a developer confirm each hit, and record which owners need to change code. Also check whether any third-party provider or internal wrapper you depend on calls those methods, because your own repository search will not reveal that.
Run the full DAG test suite against Airflow 3.2 in a staging environment that mirrors your production image and constraint file, not just on a developer laptop. Tests that only import DAG files will catch parse-time failures, but you should also execute tasks that use custom priority weight strategies so run-time failures appear before cutover. Ask the owners of any custom strategy to confirm in writing which replacement behavior they expect, because a removed method may have a replacement with different semantics. Keep the staging results as part of your change record, since they become evidence that the upgrade was tested against the code you actually run.
What to prepare before touching the 3.2 upgrade
Airflow 3.2 changes the database layer, the container images and the Python runtime at the same time, so most of the risk sits before the upgrade starts. The four to six items below are the preparation steps that let a team roll back cleanly and tell a dependency problem from an upgrade problem.
Consistent metadata database backup
Take a backup of the metadata database that captures scheduler, DAG run and task instance state at one point in time, and confirm you can restore it into a separate instance. Airflow 3.2 supports PostgreSQL 14 to 18 and MySQL 8.0, 8.4 and Innovation releases, and MariaDB is not a supported metadata database, so the backup tooling must match one of those engines. Test the restore before the migration runs.
Inventory of MySQL client usage
Search custom operators, hooks, plugins, Dockerfiles and bootstrap scripts for anything that calls the MySQL client binary or depends on it being present in the image. Airflow 3.2.0 removed the MySQL client from container images, so a task that shells out to mysql or mysqldump will fail after the image change. Record each owner and whether the call can move to a Python driver.
Custom image rebuild plan
Decide whether your images extend the official Airflow image or build from a base you maintain, then plan a rebuild that installs any MySQL client packages explicitly in your own layer if a workload still needs them. Pin the Airflow version and constraint file together so the rebuilt image does not pull unplanned provider versions. Keep the rebuilt image tag distinct from the 3.1 image so rollback stays possible.
Staging environment mirroring production executors
Build a staging environment that uses the same executor, worker image, queue layout and database engine as production, not a single-process local setup. Several executors can run in one deployment since Airflow 2.10.0, so confirm which executors production uses and that each has at least one representative DAG. Staging results only predict production when the execution path matches.
Python 3.10 to 3.14 worker confirmation
Confirm that every worker, scheduler and DAG processor image runs a Python version in the 3.10 to 3.14 range that Airflow 3.2 supports, and that the matching constraint file installs cleanly for that version. Native extensions in older database or cloud SDK packages often lag behind new Python releases, so run the full dependency install and an import test for every custom package. Confirm the Python version with your platform team before scheduling the upgrade window.
The upgrade sequence from 3.1 to 3.2 with checks and rollback points
This sequence moves a self-hosted Airflow 3.1 environment to 3.2 in an order that keeps a verified backup and a known-good image tag available at every stage. Each step ends with a check that tells the team whether it can continue or must stop and roll back.
Freeze DAG and configuration changes
The platform team and DAG authors agree on a change freeze for the duration of the upgrade, covering DAG repositories, Airflow configuration, connections, variables and pools. Record the current Airflow version, the image tags running on every component and the Git commit of each DAG bundle. The step is done when the freeze is announced, the inventory is written down and no pending merges reach production. Rollback point: the recorded inventory is the reference for restoring the exact prior state.
Back up the metadata database
The database owner takes a consistent backup of the PostgreSQL or MySQL metadata database while the schedulers are still running or after they are paused, following the backup method your database platform uses. Store the backup outside the Airflow cluster and confirm it can be restored into a scratch instance. The step closes when a restore test reads back expected DAG run and task instance counts. Rollback point: this backup is the primary recovery path if the migration fails.
Rebuild images without the MySQL client
Airflow 3.2.0 removed the MySQL client from container images, so any image that relied on it must be rebuilt. The image owner adds the MySQL client packages explicitly in a derived image only if a task or hook needs them, and pins the Airflow 3.2 base image and matching constraint files. Scan the build for missing system libraries and run a basic import test of each provider package. The step is done when the new images build cleanly and are pushed with new tags. Rollback point: the previous image tag stays in the registry and is not overwritten.
Upgrade and test a staging environment
Deploy the Airflow 3.2 images, the metadata database migration and the configuration changes to a staging environment that mirrors production's executor, database and secrets setup. Confirm that the SQLAlchemy 2.0 upgrade does not break custom code that uses database sessions directly, and that the removed TaskInstance and PriorityWeightStrategy methods are not called by any plugin or operator. The step is complete when staging schedules and runs DAGs end to end. Rollback point: staging is redeployed from the previous tag to confirm the rollback procedure works.
Run Ruff checks and the test suite
The DAG team runs Ruff with the Airflow rules and the full DAG and plugin test suite against the 3.2 environment, then reviews every finding that cannot be auto-fixed. Use the Airflow upgrade guidance to confirm that any airflow connections list calls no longer rely on the removed --conn-id option. The step closes when the checks and tests pass with no unresolved findings. Rollback point: a failure here stops the production change before any component is touched.
Decide on gunicorn for the API server
If the team adopts gunicorn for the API server, which Airflow 3.2 supports with zero-downtime worker recycling, the platform owner changes the API server start configuration in staging and checks worker count, memory and health probes under load. If the team keeps the current server, record that decision and its reason. The step is done when the chosen API server configuration is tested and documented. Rollback point: the previous API server configuration is kept in version control.
Upgrade components in order
In production, upgrade the scheduler first, then the DAG processor, then the API server, then the workers, so that each component runs a version it is compatible with. Pause new deployments during each step and watch component health after each restart. The step is done when every component reports the 3.2 image tag and the health checks pass. Rollback point: each component can be returned to the previous image tag individually while the backup is still valid.
Run database migration and verify runs and logs
Run the Airflow database migration command against the production metadata database once the scheduler and DAG processor are ready, and confirm it completes without error. Then verify that scheduled DAG runs are created, tasks execute on the workers, logs are readable in the UI and API, and no tasks are stuck in queued states. The step closes when a set of representative DAGs has completed successfully and the on-call team signs off. Rollback point: if verification fails, restore the database from the backup taken earlier and redeploy the previous image tags, then lift the freeze only after the restored system passes the same checks.
Should you adopt multi-team mode and gunicorn during this upgrade
If one team owns the Airflow environment and your current deployment works, the safest path is to complete the version move first and leave the new 3.2.0 features switched off. The upgrade itself already brings required changes: SQLAlchemy 2.0, removed TaskInstance and PriorityWeightStrategy methods, the MySQL client dropped from container images, and Python 3.14 support. Each of those needs testing, and adding more changes in the same window makes it harder to tell which change caused a failure.
- Upgrade first: Get the environment stable on 3.2.0 with existing settings before enabling anything new.
- Keep the API server as it is: Leave your current API server startup in place until the upgrade is verified.
- Record what you changed: Keep a list of every new setting so it can be reviewed in a later change.
- Plan a separate window: Schedule adoption of new features as a distinct, reviewable change.
- Confirm image contents: If your images relied on the MySQL client, confirm how you will handle that dependency.
Before closing this tab, check that scheduled runs, the API server and your deployment pipeline all behave the same on 3.2.0 as they did before the move.
Multi-team deployments were added in Airflow 3.2.0. They matter when several teams share one Airflow environment and need their workflows, access and visibility kept apart. This is a design decision as much as a configuration change, because team boundaries affect who can see DAGs, connections and runs. Confirm the exact configuration keys, limits and supported isolation boundaries in the release notes and your own tests before you rely on them.
- Define team boundaries: Decide which DAGs, connections and variables belong to which team.
- Map roles to teams: Connect team membership to your identity provider and auth manager so access follows your existing groups.
- Test cross-team access: Verify that a user on one team cannot view or trigger another team's workflows.
- Review shared resources: Identify connections, pools and secrets that teams must share and document who owns them.
- Plan operational ownership: Decide who handles on-call issues for shared scheduler and API server components.
As a closing check, ask whether the isolation you need is stronger than what a shared scheduler and metadata database can provide, and document the answer for your auditors.
Airflow 3.2.0 adds gunicorn support for the API server, with zero-downtime worker recycling. This is aimed at platform teams that run the API server continuously and want to restart or replace workers without a visible outage. The benefit is operational, so it only matters if your monitoring, health checks and deployment process are set up to take advantage of it. Confirm the supported settings and deployment method in the production deployment guide before you change your startup command.
- Change the startup command deliberately: Moving from your current API server start method to gunicorn is a configuration change that needs its own test.
- Check health probes: Make sure load balancer and Kubernetes probes still reflect real API server health during worker recycling.
- Test a recycle under load: Simulate worker replacement while users and scripts are calling the API.
- Review logging and metrics: Confirm that logs and metrics still identify the processes you need to investigate.
- Document rollback: Record how to return to the previous startup method if recycling causes errors.
Before closing this tab, confirm with your team that a gunicorn-based API server has been tested in staging with the same health checks and alerts used in production.
Adopting multi-team mode and gunicorn does not have to happen in the same change as the 3.2.0 upgrade. Splitting the work keeps each change small, makes failures easier to diagnose and gives your reviewers a clear record. Each optional feature adds its own configuration, documentation to maintain, and test cases, so it is worth counting that effort before you bundle it into a release. The sequence below is one common approach, not a required order.
- Phase one: Upgrade to 3.2.0 with existing configuration and confirm the environment is stable.
- Phase two: Adopt gunicorn for the API server in staging, then production, if your platform needs zero-downtime recycling.
- Phase three: Introduce multi-team mode once team boundaries and access rules are agreed and tested.
- Track each change: Keep separate change records, test results and rollback steps for every phase.
- Ask for scope in writing: If a partner is doing the work, request a fixed scope that names which features are included.
As a closing check, confirm that each phase has its own exit criteria so a later change can be stopped without affecting the upgrade already in production.
What makes a 3.2 upgrade longer or shorter
This table compares the factors that expand or shrink the work of moving from Airflow 3.1 to 3.2, such as custom code, images and database history. Read each row as a question to answer about your own estate before asking for a fixed-scope quote. The main takeaway is that the removed methods, the MySQL client and the SQLAlchemy 2.0 change are the items most likely to add work, while a small, well-tested estate with a clean metadata database moves faster.
| Driver | Why it changes the effort | How to keep it down |
|---|---|---|
| Custom plugins | Each plugin that touches the API server, UI or database layer must be checked against 3.2 behavior and may need code changes. | Inventory plugins first, remove unused ones and test each remaining plugin in staging. |
| Use of removed TaskInstance or PriorityWeightStrategy methods | Any DAG, operator or custom priority strategy calling methods removed in 3.2 fails until rewritten. | Search the codebase for those method names and cover the call sites with tests before the upgrade. |
| Images that depend on the MySQL client | Container images that rely on the MySQL client removed in 3.2 need a new base or an added client package, and every image must be rebuilt. | List every image and its installed packages, then decide whether to install a client in your own layer. |
| Metadata database size and history | Large run histories slow migrations and extend the downtime window, and make backups and rollback slower to verify. | Trim history with a cleanup run and take a verified backup before the migration starts. |
| Number of executors and environments | Each executor type and each environment (development, staging, production) needs its own build, test and rollout pass. | Standardize on fewer executor types and promote the same image through each environment. |
| Multi-team mode adopted in the same change | Adopting multi-team deployments alongside the upgrade adds access model, configuration and testing scope on top of the version move. | Upgrade first on a single-team setup, then plan multi-team adoption as a separate change. |
| Python 3.14 adopted in the same change | A new Python version changes dependency resolution, constraint files and worker images, which compounds with the other 3.2 changes. | Keep the Python version unchanged for the first upgrade unless your dependencies already support 3.14. |
Questions teams ask before a 3.1 to 3.2 Airflow upgrade
What does a 3.1 to 3.2 Airflow upgrade cost?
The cost is the labor to assess, change, test and cut over your Airflow environment, plus any infrastructure you run in parallel during testing. Airflow itself is released under the Apache License 2.0 and has no paid edition, so there is no license fee to the project. The main cost drivers are the number of DAG repositories, how many operators and hooks depend on removed methods or the MySQL client in images, whether your metadata database needs work first, and how much of your deployment is custom (Helm values, images, plugins, auth configuration). Ask any partner for a quote built from a written scope that lists each of these items, and ask which parts are one-time work and which recur, such as patching and upcoming upgrades.
How long does a 3.1 to 3.2 upgrade take?
The duration depends on the size and condition of your environment rather than on the version pair alone. The longest phases are usually the DAG audit, the test run of your pipelines against 3.2, and the database migration window, which depends on the size of your metadata history and how much downtime your schedules can tolerate. Multi-team mode and gunicorn for the API server add review and testing work only if you plan to use them. Ask for a schedule that separates assessment, staging, production cutover and post-upgrade monitoring, and confirm which production windows the plan assumes.
Can our own team upgrade Airflow from 3.1 to 3.2 without a partner?
Yes, a team with Airflow, Python and Kubernetes or VM experience can do the upgrade in-house, and many do. Your team should be able to read the release notes, search DAG code for the removed TaskInstance and PriorityWeightStrategy methods, rebuild images without the MySQL client, run a staging environment and perform a database migration with a tested backup. The gaps that usually matter are no spare staging capacity, no one who owns the Helm chart or deployment code, and no time in the sprint plan for pipeline fixes. A partner is useful when those gaps exist or when you want an independent check before the production cutover.
What does our staff need to provide during the upgrade?
Your staff need to supply access and knowledge that only your organization holds. Expect to provide:
- Owners for each DAG repository who can confirm expected behavior and approve fixes
- Access to staging and production clusters, the metadata database and the image registry
- The current Helm values, Dockerfiles, constraint files and auth manager configuration
- A change window approved by operations, and someone who can run the database backup and restore
- Decisions on any multi-team layout or API server worker settings you plan to adopt
Can we skip Airflow 3.2 and go straight to 3.3?
The supplied release information does not give a supported skip path, so do not assume one. Airflow 3.3 introduces its own changes, including the task and asset state store and the pandas 3 XCom change in 3.3.1, so a jump would combine the 3.2 and 3.3 work into one cutover. Check the Airflow upgrade guide and release notes for each version in the path, and confirm with your partner whether a combined move is planned as one scope or as two sequential upgrades with a stable production point in between.
How does rollback work after a 3.2 upgrade?
Rollback depends on whether the metadata database has been migrated. Once airflow db migrate has changed the schema, returning to 3.1 generally means restoring a database backup taken before the migration, so that backup must be consistent and tested. Keep the previous image tags and Helm release available, pin the prior versions in your deployment code, and record the cutover time so you know which DAG runs happened on which version. Ask your team to rehearse the restore in staging, because a backup that has never been restored is an unverified control.
Do SQLite or MariaDB deployments have to change before upgrading?
Yes, you should change them before the upgrade rather than during it. The Airflow production deployment guide says SQLite is for testing only and can lead to data loss in production, and the prerequisites list PostgreSQL 14 to 18 and MySQL 8.0, 8.4 and Innovation releases as supported metadata databases. MariaDB is not supported as a metadata database. If you run either SQLite or MariaDB, plan a migration to a supported database as a separate step with its own backup and test, and confirm the exact sequence with your partner or the Airflow documentation before scheduling the 3.2 cutover.
Does the 3.2 release affect our security or compliance evidence?
The upgrade can change evidence trails, so plan for it. Changes to the image contents, the auth manager configuration, API server workers and the metadata database all affect what your change records and logs show. Keep records of the version under test, the image digests deployed, the approved change window and the backup verification. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications; independent auditors and certification bodies do that work.
How DeployOpen scopes and delivers the 3.2 upgrade
DeployOpen runs the 3.2 upgrade as a fixed-scope engagement inside your own infrastructure: your cloud accounts, data centers or air-gapped network, with the work sequenced as inventory, staging upgrade, code and image changes, and cutover. The inventory covers the Airflow version in service, the metadata database engine and version, every custom operator, plugin and image that imports SQLAlchemy or calls removed TaskInstance or PriorityWeightStrategy methods, the airflow connections list calls in scripts that use --conn-id, and any container build that depends on the MySQL client. Scope and deliverables are agreed in writing before work starts, and the quote follows from that written scope rather than from a published price list. Ask the partner to show which inventory items are in the quote and which are assumed to be your team's work.
Staging is where the 3.2 changes are proven before production is touched. The staging upgrade should use a copy of your production metadata database, a rebuilt image without the MySQL client, and a test run of your DAGs against the new SQLAlchemy 2.0 behavior and the gunicorn-backed API server. Decide with your team who owns the sign-off on each step, which production windows are available, and how a rollback would be executed. Cutover, dependent on your release process, is planned with your change management records. Ongoing support, upgrade assistance for later Airflow releases and continuous testing are available as a retainer, priced separately from the fixed-scope upgrade. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform that work, so confirm early which evidence your auditor will expect from the upgrade.
How DeployOpen plans Airflow upgrades
DeployOpen plans the move from Apache Airflow 3.1 to 3.2 as a written, fixed-scope engagement inside your own infrastructure. The work starts with an inventory of your DAGs, providers, database and deployment, then builds and tests the upgrade in a staging environment before any production change.
How we scope
- Inventory your Airflow 3.1 deployment, including executors, metadata database, images and any Helm chart values
- Map which DAGs and tasks touch TaskInstance or PriorityWeightStrategy methods removed in 3.2
- Confirm whether any image or job still depends on the MySQL client removed from container images
- Agree in writing whether multi-team mode and gunicorn for the API server are in or out of scope
How we build
- Upgrade a staging copy of the scheduler, DAG processor, API server, workers and metadata database first
- Test SQLAlchemy 2.0 behavior against your custom operators, hooks and any direct database queries
- Rebuild images on the Python version you run, confirming Python 3.14 support against your dependencies
- Run the Ruff Airflow rule checks and the DAG test suite before and after each change
How we hand over
- Deliver a written runbook covering the upgrade order, database migration steps and verification checks
- Document the rollback plan and the backup taken before the metadata database migration
- Record configuration changes for the API server, including any gunicorn settings, in your repository
- Walk your platform and data engineering teams through the changes and the open items
How we support
- Agree whether post-upgrade support is needed through a retainer, which is available for ongoing support and upgrades
- Review scheduler and API server behavior after cutover against the agreed checks
- Plan the follow-on move to Airflow 3.2 patch releases and later minor lines as separate, scoped work
- Ask for the support terms, response expectations and handover scope in the written quote before work starts
