How to plan a Flowable database schema upgrade before the engine changes
Before the Flowable engine changes version, the database schema must match the library version, because the engine checks the two at startup and refuses to run on a mismatch. The decision your team has to make is how the schema changes: either the engine upgrades it automatically at start, or a DBA runs the upgrade DDL scripts ahead of the deployment. Choose that path during planning, not on release day, since it determines who holds the change, when the database is touched and how you roll back.
Start by mapping the supported path. Flowable 8.0.0 was released on February 27, 2026, following 7.2.0 on August 21, 2025 and 7.1.0 on October 7, 2024. If you are still on an older 6.x or 7.x line, confirm the intermediate schema versions you must pass through with the release notes in the Flowable 8.0.0 release notes and the configuration docs, rather than assuming a direct jump is safe. The order of the schema change is set by your application and engine upgrade plan: the schema step belongs in the same runbook as the dependency and framework changes, and it should be rehearsed against a restored copy of production data.
Write down the controls around the change before you run it. Take and verify a database backup first, as the Flowable configuration docs advise, and record who approves the schema step, who can restore it and how long a restore takes in your environment. If you run rolling application deployments, confirm that old and new engine nodes will not operate against a schema they cannot read, because a mismatch surfaces as a FlowableWrongDbException at startup. Ask your team to confirm the databaseSchemaUpdate setting in each environment, since an unexpected value there is the most common reason an upgrade behaves differently from the rehearsal.
What changes in the release notes and what each change means for the schema upgrade
This table lists the platform changes in the Flowable 7.0.0 and 8.0.0 release notes and separates them by who feels them. The schema change itself follows the engine version, while the rest of the list affects the application that starts the engine, so each row names the action your team needs. Read the schema-driven rows first, then plan the application changes that must ship alongside them.
| Release change | Affects the schema upgrade? | What it means for the upgrade path | Action for the team |
|---|---|---|---|
| Java 17 baseline (7.0.0) | No, runtime only | The engine and the process that hosts it must run on Java 17 before the schema step can run at startup. | Confirm JDK 17 in every node image and batch job that starts the engine. |
| Spring Boot 3 and Jakarta EE namespace (7.0.0) | No, application layer | Hosting applications must move from javax to jakarta packages, so the startup code that triggers schema checks changes too. | Plan the namespace change in the same release train as the first engine start on 7.x. |
| Removal of UI apps, form and content engines, Mule and async history (7.0.0) | Yes, indirectly | Tables and configuration tied to removed components are no longer maintained, so confirm which schema objects your version still uses. | Inventory deployed tables and drop configuration that references removed components before the upgrade. |
| Spring Framework 7 and Spring Boot 4 (8.0.0) | No, application layer | There is no Spring Boot 3 compatibility in 8.0.0, so the application server or host must move before the engine can start. | Sequence the Spring upgrade with the 8.0.0 engine and test startup in a staging copy of the database. |
| Jackson 3 default with Jackson 2 compatibility layer (8.0.0) | No, runtime behavior | Changes to JSON handling do not alter tables, but variables stored as JSON must still deserialize after the engine starts. | Run a read test of stored JSON variables against the upgraded engine before cutover. |
| Removal of JUnit 3 and 4 support (8.0.0) | No, test suite only | Schema upgrade test jobs that rely on old test harnesses will not run, which can hide a failed upgrade rehearsal. | Move upgrade rehearsal scripts to JUnit 5 or a non-test harness before the window. |
Automatic upgrade at engine start or DBA-run scripts: which fits your environment
In development and test, setting databaseSchemaUpdate to true is usually the practical choice. The engine checks at startup that the library version matches the database schema version, and with that property enabled it upgrades the schema itself, which keeps developers moving when they change engine versions. The cost of a mistake is limited to disposable data, so the main risk is teams forgetting that the same configuration may later reach shared environments.
- Disposable databases: Recreate the schema from scratch often, so automatic upgrades rarely need to be reversed.
- Test fixtures: Confirm that test suites start against an empty and an upgraded schema, since both paths can behave differently.
- Configuration drift: Keep the property out of production profiles, so a shared base configuration does not carry it forward.
- Version pinning: Record the exact engine version in build files so every developer upgrades at the same point.
- Upgrade rehearsal: Practice the upgrade on a copy of realistic data volume before it reaches staging.
Before relying on this path, confirm which engine version and database type your test environment uses against the Flowable configuration documentation, and check that your test database is not also used for shared integration work.
Staging with CI-driven deploys is where automatic upgrades start to need controls. Pipelines deploy the application and engine together, and a failed start can leave the schema partly changed while the old application version still runs. Automatic upgrades can work here if the pipeline treats schema change as a tracked event, but the team must decide who approves it and how a failed upgrade is recovered.
- Backups before deploy: The Flowable docs say to back up the database first, so make the pipeline take and verify a snapshot before startup.
- Version mismatch handling: A library and schema mismatch throws an exception at startup, so test that the pipeline fails loudly rather than retrying into a bad state.
- Single-writer assumption: Confirm that only one deployment upgrades the schema at a time, or that concurrent pods do not race on DDL.
- Rollback path: Decide whether the previous application version can run against the new schema, since many upgrades are one-way.
- Promotion evidence: Keep the pipeline logs showing the schema version before and after each upgrade.
Before promoting to production, confirm that the staging schema was produced by the same path you intend to use in production, because a path that differs between environments hides the failures you need to see.
In regulated production, the DBA script path is usually the stronger control. The DBA reviews the DDL that Flowable's upgrade scripts apply, schedules the change inside an approved window, and records who ran it and when. Automatic upgrade at engine start moves that decision into application startup, where change approval, segregation of duties and rollback planning are harder to evidence, so the property should be off unless your change process explicitly accepts that trade-off.
- Reviewed DDL: The DBA reads the scripts for the target version and the database type in use before they run.
- Separation of duties: Application deployers do not hold the DDL privilege needed for the upgrade.
- Change records: Link each schema change to a ticket, the approving owner and the backup identifier.
- Sequencing: Plan how the schema change interleaves with rolling application deployments, since old and new nodes may run during the window.
- Auditor evidence: Keep script hashes, execution logs and post-upgrade version checks for later review.
Before choosing this path, confirm with your DBA and change board which controls they require, and confirm with Flowable which upgrade scripts apply to your exact version pair.
Backups, inventory and a test database to prepare before the schema changes
Schema changes are hard to reverse once they run against production, so the preparation work matters more than the upgrade command itself. The four cards below cover what to protect, what to inventory, where to rehearse and which database types and versions need checking first.
Verified database backup first
The Flowable configuration docs tell you to back up the database before any schema upgrade, whether the engine runs it at start or a DBA runs the DDL scripts. A backup only counts once it has been restored successfully, so confirm the restore procedure, the time it takes and who is authorized to execute it. Record the backup identifier in the change ticket so a rollback target is unambiguous.
Inventory of custom schema touchpoints
List every custom query, reporting view, stored procedure, ETL job and external tool that reads or writes Flowable tables. Schema changes can break these silently, because the engine will not know they exist. Include DBA-owned scripts and backup jobs that reference table or column names, and assign an owner to each item so retesting after the upgrade has a clear list.
Restored production copy for rehearsal
Restore a recent production backup into a non-production environment and run the full upgrade there, starting from the same engine version. Measure how long the schema change takes on production-sized data, then start the application and check that running process instances, timers and jobs still behave. Keep the rehearsal log so the production runbook reflects what actually happened.
Confirm the database types in use
Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server. Record the exact product and version of each database in every environment, including the one used by test suites, because the upgrade script set is selected per database type. Confirm that the upgrade scripts you plan to run match that type and that your DBA tools support it.
MySQL versions below 5.6.4
The Flowable configuration docs note that MySQL versions below 5.6.4 lack millisecond precision. If any environment runs an older MySQL, confirm how timestamp columns are defined before the upgrade and check that history and job timing still read correctly afterward. Plan the database upgrade as its own change if the server version must also move.
The upgrade sequence: schema, application and rolling deployment with checks at each step
This sequence moves a Flowable database schema and the engine version together, with a check and a rollback point at each step so that no node runs against a schema it cannot read.
Take and verify a full database backup
Before any change, the database owner takes a full backup of the Flowable schema and confirms it can be restored. The Flowable configuration docs say to back up the database before upgrading the schema, so this is the first step, not an optional one. Confirm the backup covers the schema and any tables your application adds, and record its location and time. Done means a restore test on a separate host has been started and the backup file is checksummed. This backup is your rollback point for everything that follows.
Rehearse the upgrade on a restored copy
The platform team restores the backup into a non-production environment with the same database type and version as production, then runs the full sequence against it. Include the existing process definitions, running instances and timer jobs, because these reveal problems that an empty schema will not. Check that the engine starts, that deployed definitions load and that a sample of running instances can continue. Record every error and the exact steps taken. Done means the rehearsal completes with a written runbook that the DBA and the application owner have both reviewed.
Generate and review the DDL scripts
Decide whether the engine will upgrade the schema at start or whether a DBA will apply the upgrade DDL scripts by hand. With databaseSchemaUpdate set to true, the engine upgrades the schema automatically. Many regulated teams prefer the DDL route so the change can be reviewed and approved as a file. In either case, the DBA reviews the scripts for your database type, checks them against the engine version you are moving to, and confirms the change is in the approved change record. Done means a signed-off script set exists and matches the rehearsed version.
Apply the schema changes in the planned window
During the agreed window, the DBA applies the reviewed DDL scripts to production while the old engine version is stopped or drained. Monitor the database for locks and long-running statements, and keep the backup available until the last check in this sequence passes. Do not start the new engine against a partially upgraded schema. Done means the scripts have completed without error and the schema version recorded in the database matches the target engine version. If a script fails, restore from the backup rather than editing the schema by hand.
Deploy the new engine to one node
Start a single node running the new Flowable engine version against the upgraded schema. At startup the engine compares its library version with the schema version. If the two do not match, the engine throws FlowableWrongDbException, which signals a version mismatch between the database schema and the engine. Treat that exception as a stop signal: do not force the start or edit the version table. Done means the node starts, logs no version mismatch and reports healthy on your monitoring. Until other nodes are moved, this node is the rollback canary.
Confirm the async executor hands over jobs safely
Before moving the other nodes, verify the async executor on the upgraded node. The executor coordinates nodes through lock owners and lock expiration times stored in the database, so a job locked by an old node is recovered only after its lock expires. Check that timers and async jobs are being picked up, and that no job is stuck on a lock from a stopped node. Done means job execution on the new node is visible in your operations tooling and no jobs show an unexpected lock owner.
Roll out the remaining nodes one at a time
Move the remaining nodes to the new engine version in small steps, draining each old node so that its running jobs finish or its locks expire before it stops. Watch the error logs, job failure counts and the number of active instances after each node moves. Keep the old application artifacts available so any node can be reverted while the rollout is open. Done means every node runs the new version, no node reports a version mismatch, and job throughput matches the pre-upgrade baseline. Record the time the rollout closed and retire the backup only after the agreed observation period ends.
Why version mismatch errors stop an engine from starting
At engine start, Flowable compares the version of the engine library with the version recorded in the database schema. If they do not match, the engine throws an exception and does not come up, and the error the engine raises for this condition is FlowableWrongDbException. The check protects you from running engine code against tables it does not expect, so treat the exception as a safety stop rather than a bug to suppress. Before you change anything, confirm which engine version and which schema version each environment carries, and find out whether your deployment sets databaseSchemaUpdate to true (automatic upgrade at start) or relies on a DBA to apply the upgrade DDL scripts. The Flowable configuration docs describe both paths and tell you to back up the database first.
Mixed versions during a rolling deployment are the most common way this error appears in production. If the new library runs with automatic schema upgrade enabled, the first node to start may migrate the schema while older nodes still run the previous library. Those older nodes then hit the mismatch when they restart or reconnect, and an orchestrator that keeps restarting them can turn one failed start into a loop. Decide before the rollout which node upgrades the schema, whether that happens once through a DBA-run script before any new node starts, and what the old nodes do while the schema is in its new state. Confirm this sequence in a non-production copy of your database rather than assuming the engine will handle it.
Check the schema version before and after each node is replaced, not only at the start and end of the release. Query the Flowable version table in the target database (the name and columns depend on your engine version and database type, so confirm them against your schema scripts), record the value, and compare it with the library version in the node's build. Add the check to your deployment runbook as a gate: a node is not replaced until the schema matches what its library expects, and a rollback is not started until you know which schema version the previous library needs. Keep these checks in your change record, because they are the evidence that the sequence ran as designed.
What makes a schema upgrade take longer
This table lists the factors that change how long a Flowable schema upgrade takes and how much coordination it needs. Read each row as a question to answer about your own environment before you agree on a plan and a window. The main takeaway is that data volume, shared databases and DBA review usually matter more than the DDL itself.
| Driver | Why it matters | What to check |
|---|---|---|
| Table count and history volume | Upgrade scripts alter existing tables, and large history tables take longer to rewrite or index, which extends the window the database is changed. | Row counts for the Flowable runtime and history tables, and whether history retention is set or unbounded. |
| Database type and version | Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server, and each has different DDL behavior and locking. | Your exact database product and version, and whether the Flowable configuration docs list it for the target release. |
| MySQL version below 5.6.4 | The configuration docs note these versions lack millisecond precision, which affects timestamp columns the upgrade may touch. | Whether any MySQL server in use is below 5.6.4 and how timestamp columns are defined today. |
| Custom tables and queries | Reporting views, custom tables or native queries that read Flowable tables can break when columns or indexes change. | An inventory of every SQL object, stored procedure and report that references Flowable table names. |
| Shared database | If other applications use the same schema or instance, their maintenance windows, locks and permissions constrain the upgrade. | Which applications connect to the database, their owners, and whether Flowable has its own schema or user. |
| Number of running nodes | Nodes on mixed versions can fail the version check at start, so the sequence of node restarts drives both downtime and rollback options. | How many engine nodes share the database, and whether the deployment can run old and new nodes side by side. |
| DBA review of DDL | Organizations that require a DBA to approve scripts add review, change tickets and scheduling time before any run. | Your change approval steps, lead time for DBA review, and whether scripts must run under a separate privileged account. |
| Backup and restore process | The docs say to back up first, and a restore test confirms the backup is usable if the upgrade fails partway. | Backup method, time to restore in a test environment, and whether the restore has been verified for this schema version. |
Questions teams ask before upgrading the Flowable schema
What does a Flowable schema upgrade cost, and who pays for what?
The cost is mostly labor, split between your team and any partner you hire. Your side covers database access, change approvals, DBA time to review and run scripts, application owners who test process behavior, and the maintenance window. A partner's fee, if you use one, follows from a written scope that lists the environments, the engine versions involved, and whether the work includes a test plan and runbook. The DDL execution itself is usually a small part of the effort. Most of the cost is one-time for the upgrade, with recurring cost only if you retain a partner for later upgrades. No supplied figure sets a price, so ask each bidder to itemize these components and to state what is excluded.
How long does a Flowable schema upgrade take, and what sets that?
Duration depends on the size of the tables the upgrade touches, the number of environments that must be upgraded in order, the depth of regression testing your process models need, and how quickly approvals and maintenance windows can be scheduled. Run-time execution on a large production database can be the longest single step, so measure it on a copy of production rather than estimating it. Ask your database vendor or a partner to confirm the expected execution time for your data volume, and confirm the exact script sequence for your source and target versions in the Flowable configuration documentation before you commit to a date.
What must our team provide before the upgrade starts?
You need to provide several things before any schema change runs:
- Database access for a test copy, staging and production, with credentials held under your own control
- DBA time to review the scripts, check the database type and version, and approve execution
- A recent, tested backup, because the Flowable configuration documentation says to back up the database first
- Application owners who can confirm process definitions, custom delegates and REST clients still behave correctly
- A test copy that reflects production data volumes, so timing and locking can be observed
If any of these is missing, the upgrade schedule is likely to slip.
Can our own team upgrade the Flowable schema using the Flowable docs?
Yes, many teams can, provided they have database administration skills and engineers who understand their process and case models. The Flowable configuration documentation describes two paths: automatic upgrade when the engine starts with schema updates enabled, or running the upgrade DDL scripts manually. The second path gives DBAs control over timing and review. Consider a partner if your team has not run a Flowable upgrade before, if you lack a test environment that mirrors production, or if the upgrade must be coordinated with an application upgrade. Ask any partner to show a written scope, a rollback plan and a test approach before you sign.
Is automatic schema upgrade at engine start acceptable in production?
In most regulated environments, automatic upgrade at engine start is hard to justify for production. With schema updates enabled, the engine checks that the library and schema versions match and upgrades the schema when it starts, which means the change runs as a side effect of a deployment. A DBA-run script lets you review the DDL, take and verify a backup, schedule the change, and document approval for auditors. Automatic upgrade can be reasonable in development and test environments, where the cost of a failed change is low. Decide the production path in your change policy and confirm it with your Flowable version and database vendor.
How do we roll back a failed Flowable schema upgrade?
Rollback depends on your backup and on whether the scripts can be reversed. Flowable's documentation tells you to back up the database before upgrading, so the most reliable rollback is a verified restore of that backup, followed by redeploying the matching application version. Confirm with your database vendor how a point-in-time restore works for your platform, and test the restore on a copy before the production window. Rehearse the full sequence, including application rollback, because a restored schema must match the engine version that runs against it. Write the rollback criteria and the decision owner into the change plan before execution.
How DeployOpen scopes and delivers a Flowable schema upgrade
DeployOpen plans Flowable database schema upgrades as part of a written scope that covers the engine version change, the database and the deployment pipeline. We decide with your DBA and platform team whether the engine upgrades the schema at start or whether scripts run under DBA control, then build, test and document the sequence inside your own infrastructure.
How we scope
- Inventory the current Flowable version, database type and schema version across every environment and engine node.
- Agree in writing whether schema changes run at engine start or through DBA-run upgrade scripts.
- Define the backup, restore point and rollback steps the database owner must confirm before any change.
How we build
- Rehearse the schema upgrade on a copy of production data before any shared environment is touched.
- Sequence schema changes with rolling application deployments so old and new nodes stay compatible during the window.
- Test version mismatch handling so a node with the wrong library version fails clearly rather than running against the wrong schema.
How we hand over
- Deliver the upgrade runbook, DDL scripts used, and the ordered steps for each environment.
- Document the verification checks for schema version, async executor jobs and process instance state after the change.
- Walk your DBA and platform team through the rollback path and the conditions that trigger it.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer for later Flowable releases.
- Confirm with us during scoping which support terms, response expectations and access arrangements apply to your environment.
