Apache DolphinScheduler has added an automatic version upgrade feature since version 2.0.1. The official documentation provides a one-click upgrade script: sh ./script/create-dolphinscheduler.sh If it's a minor version update, simply executing the script suffices. However, upgrading across multiple major versions can still encounter issues. Here's a summarized guide. (Applicable for upgrades from 1.x → 2.x or 2.x → 3.x) I. Pre-Upgrade Preparations Data Backup

Database Backup: Backup the DolphinScheduler metadata database (MySQL/PostgreSQL) mysqldump -u[username] -p[password] dolphinscheduler > dolphinscheduler_backup.sql Configuration Backup: Backup all configuration files under the conf/ directory (e.g., application.yaml, common.properties)
Resource Backup: Backup custom scripts, JAR packages, and other resources in the resources/ directory Version Compatibility Check

Verify whether the current version supports direct upgrades to the target version (e.g., upgrading from 2.0.5 to 3.1.0 requires checking the official compatibility matrix)
Ensure JDBC driver, ZooKeeper, and other dependency versions meet the target version requirements



Environment Check

Confirm server resources (CPU/memory/disk) meet the new version's minimum requirements
Stop all running scheduling tasks to avoid task state loss during upgrade II. Upgrade Steps Stop All DolphinScheduler Services Stop all services based on your deployment method. For cluster deployments, use: sh ./script/stop-all.sh [[2, 3]] Database Upgrade Modify configurations in ./bin/env/dolphinscheduler_env.sh (replace {user} and {password} with your database credentials).
For MySQL: export DATABASE=${DATABASE:-mysql}
   export SPRING_PROFILES_ACTIVE=${DATABASE}
   export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&useSSL=false"
   export SPRING_DATASOURCE_USERNAME={user}
   export SPRING_DATASOURCE_PASSWORD={password} Manually download the mysql-connector-java driver and place it in ./tools/libs [[3, 5]]
Execute the database upgrade script: sh ./tools/bin/upgrade-schema.sh Service Upgrade Update configurations in bin/env/install_config.conf based on your deployment:


Pseudo-Cluster: Follow Pseudo-Cluster Deployment Guide


Cluster: Follow Cluster Deployment Guide



Restart services: sh ./bin/start-all.sh III. Post-Upgrade Verification Service Health Check curl [http://localhost:12345/dolphinscheduler/actuator/health ](http://localhost:12345/dolphinscheduler/actuator/health )  # Check API health
   tail -n 100 logs/api-server.log                               # Check logs for errors Task Execution Test

Manually trigger a test workflow to confirm scheduling, execution, and alerting
Verify historical task states are fully migrated


Functionality Compatibility Check

Ensure APIs, custom plugins, tenant configurations, and UI operations (e.g., workflow definition) work normally IV. Rollback Plan Database Restoration mysql -u[username] -p[password] dolphinscheduler < dolphinscheduler_backup.sql Service Rollback

Stop the new version and restore the old installation directory
Restart services using old configurations V. Important Notes Incremental Upgrades

For upgrades from 1.x to 3.x, follow sequential steps (e.g., 1.3.9 → 2.0.5 → 3.1.0) [[8, 9]]


Database Migration

To switch database types (e.g., MySQL → PostgreSQL), rebuild the database using scripts under sql/create/


Plugin Compatibility

Custom alert plugins and task types must adapt to the new version's SPI interfaces


Community Support

Refer to the Official Upgrade Documentation for troubleshooting Apache DolphinScheduler has added an automatic version upgrade feature since version 2.0.1. The official documentation provides a one-click upgrade script: sh ./script/create-dolphinscheduler.sh sh ./script/create-dolphinscheduler.sh If it's a minor version update, simply executing the script suffices. However, upgrading across multiple major versions can still encounter issues. Here's a summarized guide. (Applicable for upgrades from 1.x → 2.x or 2.x → 3.x) (Applicable for upgrades from 1.x → 2.x or 2.x → 3.x) I. Pre-Upgrade Preparations Data Backup

Database Backup: Backup the DolphinScheduler metadata database (MySQL/PostgreSQL) Data Backup Database Backup: Backup the DolphinScheduler metadata database (MySQL/PostgreSQL) Data Backup Database Backup: Backup the DolphinScheduler metadata database (MySQL/PostgreSQL) Database Backup : Backup the DolphinScheduler metadata database (MySQL/PostgreSQL) Database Backup mysqldump -u[username] -p[password] dolphinscheduler > dolphinscheduler_backup.sql mysqldump -u[username] -p[password] dolphinscheduler > dolphinscheduler_backup.sql Configuration Backup: Backup all configuration files under the conf/ directory (e.g., application.yaml, common.properties) Resource Backup: Backup custom scripts, JAR packages, and other resources in the resources/ directory Configuration Backup : Backup all configuration files under the conf/ directory (e.g., application.yaml , common.properties ) Configuration Backup conf/ application.yaml common.properties Resource Backup : Backup custom scripts, JAR packages, and other resources in the resources/ directory Resource Backup resources/ Version Compatibility Check

Verify whether the current version supports direct upgrades to the target version (e.g., upgrading from 2.0.5 to 3.1.0 requires checking the official compatibility matrix)
Ensure JDBC driver, ZooKeeper, and other dependency versions meet the target version requirements Environment Check

Confirm server resources (CPU/memory/disk) meet the new version's minimum requirements
Stop all running scheduling tasks to avoid task state loss during upgrade Version Compatibility Check Verify whether the current version supports direct upgrades to the target version (e.g., upgrading from 2.0.5 to 3.1.0 requires checking the official compatibility matrix)
Ensure JDBC driver, ZooKeeper, and other dependency versions meet the target version requirements Version Compatibility Check Version Compatibility Check Verify whether the current version supports direct upgrades to the target version (e.g., upgrading from 2.0.5 to 3.1.0 requires checking the official compatibility matrix) Ensure JDBC driver, ZooKeeper, and other dependency versions meet the target version requirements Verify whether the current version supports direct upgrades to the target version (e.g., upgrading from 2.0.5 to 3.1.0 requires checking the official compatibility matrix ) official compatibility matrix Ensure JDBC driver, ZooKeeper, and other dependency versions meet the target version requirements Environment Check Confirm server resources (CPU/memory/disk) meet the new version's minimum requirements
Stop all running scheduling tasks to avoid task state loss during upgrade Environment Check Environment Check Confirm server resources (CPU/memory/disk) meet the new version's minimum requirements Stop all running scheduling tasks to avoid task state loss during upgrade Confirm server resources (CPU/memory/disk) meet the new version's minimum requirements Stop all running scheduling tasks to avoid task state loss during upgrade II. Upgrade Steps Stop All DolphinScheduler Services Stop all services based on your deployment method. For cluster deployments, use: sh ./script/stop-all.sh sh ./script/stop-all.sh [[2, 3]] Database Upgrade Modify configurations in ./bin/env/dolphinscheduler_env.sh (replace {user} and {password} with your database credentials).
For MySQL: Modify configurations in ./bin/env/dolphinscheduler_env.sh (replace {user} and {password} with your database credentials). For MySQL: Modify configurations in ./bin/env/dolphinscheduler_env.sh (replace {user} and {password} with your database credentials). ./bin/env/dolphinscheduler_env.sh {user} {password} For MySQL: export DATABASE=${DATABASE:-mysql}
   export SPRING_PROFILES_ACTIVE=${DATABASE}
   export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&useSSL=false"
   export SPRING_DATASOURCE_USERNAME={user}
   export SPRING_DATASOURCE_PASSWORD={password} export DATABASE=${DATABASE:-mysql}
   export SPRING_PROFILES_ACTIVE=${DATABASE}
   export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&useSSL=false"
   export SPRING_DATASOURCE_USERNAME={user}
   export SPRING_DATASOURCE_PASSWORD={password} Manually download the mysql-connector-java driver and place it in ./tools/libs [[3, 5]] Execute the database upgrade script: Manually download the mysql-connector-java driver and place it in ./tools/libs [[3, 5]] mysql-connector-java driver ./tools/libs Execute the database upgrade script: sh ./tools/bin/upgrade-schema.sh sh ./tools/bin/upgrade-schema.sh Service Upgrade Update configurations in bin/env/install_config.conf based on your deployment:


Pseudo-Cluster: Follow Pseudo-Cluster Deployment Guide


Cluster: Follow Cluster Deployment Guide Restart services: Update configurations in bin/env/install_config.conf based on your deployment: Pseudo-Cluster: Follow Pseudo-Cluster Deployment Guide


Cluster: Follow Cluster Deployment Guide bin/env/install_config.conf Pseudo-Cluster: Follow Pseudo-Cluster Deployment Guide Cluster: Follow Cluster Deployment Guide Pseudo-Cluster: Follow Pseudo-Cluster Deployment Guide Pseudo-Cluster: Follow Pseudo-Cluster Deployment Guide Pseudo-Cluster Deployment Guide Cluster: Follow Cluster Deployment Guide Cluster: Follow Cluster Deployment Guide Cluster Deployment Guide Restart services: sh ./bin/start-all.sh sh ./bin/start-all.sh III. Post-Upgrade Verification Service Health Check Service Health Check Service Health Check curl [http://localhost:12345/dolphinscheduler/actuator/health ](http://localhost:12345/dolphinscheduler/actuator/health )  # Check API health
   tail -n 100 logs/api-server.log                               # Check logs for errors curl [http://localhost:12345/dolphinscheduler/actuator/health ](http://localhost:12345/dolphinscheduler/actuator/health )  # Check API health
   tail -n 100 logs/api-server.log                               # Check logs for errors Task Execution Test

Manually trigger a test workflow to confirm scheduling, execution, and alerting
Verify historical task states are fully migrated Functionality Compatibility Check

Ensure APIs, custom plugins, tenant configurations, and UI operations (e.g., workflow definition) work normally Task Execution Test Manually trigger a test workflow to confirm scheduling, execution, and alerting
Verify historical task states are fully migrated Task Execution Test Manually trigger a test workflow to confirm scheduling, execution, and alerting Verify historical task states are fully migrated Manually trigger a test workflow to confirm scheduling, execution, and alerting Verify historical task states are fully migrated Functionality Compatibility Check Ensure APIs, custom plugins, tenant configurations, and UI operations (e.g., workflow definition) work normally Functionality Compatibility Check Ensure APIs, custom plugins, tenant configurations, and UI operations (e.g., workflow definition) work normally Ensure APIs, custom plugins, tenant configurations, and UI operations (e.g., workflow definition) work normally IV. Rollback Plan Database Restoration Database Restoration Database Restoration mysql -u[username] -p[password] dolphinscheduler < dolphinscheduler_backup.sql mysql -u[username] -p[password] dolphinscheduler < dolphinscheduler_backup.sql Service Rollback

Stop the new version and restore the old installation directory
Restart services using old configurations Service Rollback Stop the new version and restore the old installation directory
Restart services using old configurations Service Rollback Stop the new version and restore the old installation directory Restart services using old configurations Stop the new version and restore the old installation directory Restart services using old configurations V. Important Notes Incremental Upgrades

For upgrades from 1.x to 3.x, follow sequential steps (e.g., 1.3.9 → 2.0.5 → 3.1.0) [[8, 9]] Database Migration

To switch database types (e.g., MySQL → PostgreSQL), rebuild the database using scripts under sql/create/ Plugin Compatibility

Custom alert plugins and task types must adapt to the new version's SPI interfaces Community Support

Refer to the Official Upgrade Documentation for troubleshooting Incremental Upgrades For upgrades from 1.x to 3.x, follow sequential steps (e.g., 1.3.9 → 2.0.5 → 3.1.0) [[8, 9]] Incremental Upgrades For upgrades from 1.x to 3.x, follow sequential steps (e.g., 1.3.9 → 2.0.5 → 3.1.0) [[8, 9]] For upgrades from 1.x to 3.x, follow sequential steps (e.g., 1.3.9 → 2.0.5 → 3.1.0) [[8, 9]] Database Migration To switch database types (e.g., MySQL → PostgreSQL), rebuild the database using scripts under sql/create/ Database Migration To switch database types (e.g., MySQL → PostgreSQL), rebuild the database using scripts under sql/create/ To switch database types (e.g., MySQL → PostgreSQL), rebuild the database using scripts under sql/create/ sql/create/ Plugin Compatibility Custom alert plugins and task types must adapt to the new version's SPI interfaces Plugin Compatibility Custom alert plugins and task types must adapt to the new version's SPI interfaces Custom alert plugins and task types must adapt to the new version's SPI interfaces Community Support Refer to the Official Upgrade Documentation for troubleshooting Community Support Refer to the Official Upgrade Documentation for troubleshooting Refer to the Official Upgrade Documentation for troubleshooting Official Upgrade Documentation

Arweave

Apache

Cluster

Guide

Everything You Need to Know About The Apache DolphinScheduler Version Upgrade

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

A 10-Minute Deep Dive Into the Core Architecture of Apache SeaTunnel and DataX

How to Seamlessly Transfer From Airflow to Apache DolphinScheduler With Air2phin

A Comprehensive Guide to Building DolphinScheduler 3.2.0 Production-Grade Cluster Deployment

How to Regularly Delete Log Instances in DolphinScheduler

How to Enable Auto-Start for Apache DolphinScheduler

A 10-Minute Deep Dive Into the Core Architecture of Apache SeaTunnel and DataX

How to Seamlessly Transfer From Airflow to Apache DolphinScheduler With Air2phin

A Comprehensive Guide to Building DolphinScheduler 3.2.0 Production-Grade Cluster Deployment

How to Regularly Delete Log Instances in DolphinScheduler

How to Enable Auto-Start for Apache DolphinScheduler

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps