Changing the database under a Flowable deployment

A plan for moving a live Flowable application from one supported database to another, including schema creation, data copy, in-flight jobs and the cutover window. Effort depends on the engine version, the history volume and how much custom SQL the application carries.

On this page

Changing the Flowable database without losing running work

Consider a team that must move a Flowable application from Oracle or Microsoft SQL Server to PostgreSQL while process instances, timers and history are still live. The move is a data and schema migration with a cutover, not a redeployment of process models. The BPMN, CMMN and DMN definitions can stay as they are, but the rows that hold running instances, pending jobs, variables and history have to arrive in the new database intact, and the application has to switch to them at a planned moment. Effort depends mainly on four things: how much data and history the engine holds, how much job and timer state is in flight, how much custom SQL or reporting depends on the source database, and how long the cutover window can be.

Flowable supplies the schema side. The configuration docs list postgres as a supported database type and ship create, drop and upgrade scripts per database, named in the form flowable.{db}.{create|drop}.{type}.sql. The engine tables are required and the history tables are optional, so the team must decide which history tables move and which are retired or archived. In many organizations the DDL is run by database administrators rather than the application team, so the schema owner should be named early. Flowable does not copy the data. The team owns the extract, the load, and the checks that row counts, variable values, job due dates and lock fields match between source and target before the application is pointed at PostgreSQL. Ask for a written list of the tables and columns that a DeployOpen engagement would verify, and confirm with Flowable which engine version and script set match your target.

The riskiest part is the job state. The async executor stores lock owners and lock expiration times in the database, so jobs that were locked on the old database must be released or drained before the final copy, or they will be picked up late or twice. Plan the cutover so that the old nodes stop accepting new work, timers are allowed to reach a known state, and the copy happens after that point. For the database platform itself, check the PostgreSQL upgrading documentation for the logical replication option, which can keep the target in sync and shorten the final switch. Confirm the target PostgreSQL version against the PostgreSQL versioning policy before you commit to it, since support windows differ by major version.

Which Flowable database objects carry over and which need work

This table compares each group of Flowable database objects against a PostgreSQL target, showing what can be copied as-is and what needs a decision. Read the rows marked as decisions before any data copy starts, because they determine the schema, timestamp handling and cutover checks. The main takeaway is that engine tables follow the vendor DDL, while history, locks, custom SQL and timestamps need explicit verification.

ObjectCarries over as-isWhat to check or decide
Engine runtime tablesUsually yes, when the target schema is created from the PostgreSQL vendor DDL script for the same Flowable versionConfirm the Flowable version matches on source and target before copying rows
History tablesOptional in the schema, so copy only if your deployment created themDecide whether history is migrated, archived or left in the source database
Async executor lock columnsNot a copy target: lock owners and expiry times are transientDrain or pause the executor before cutover so no stale locks are carried over
Process definitions and deploymentsCopyable when the deployment resources are unchangedVerify the BPMN and DMN resources deploy and parse on the new engine
Process and task variablesStored as serialized or typed values that may depend on the source column typeCheck large or binary variables and any custom serializers before copying
Timestamp columnsMap to PostgreSQL timestamp types, but precision differs by sourceCompare precision per source; MySQL below 5.6.4 lacks millisecond precision, so check timestamps
Custom tables and application SQLNot managed by Flowable, so it does not move automaticallyRewrite vendor-specific SQL, functions, sequences and case-sensitive identifiers for PostgreSQL
Identifier and sequence handlingEngine IDs are generated by Flowable, so the schema must be created before data is loadedConfirm how IDs are generated and reset any sequences after the copy

Documented scripts and engine paths for the schema

Flowable ships database-specific schema scripts for each supported database, so the target schema can come from vendor-provided DDL rather than hand-written tables. The cards below cover what those scripts contain, which tables are mandatory, who usually runs them, and where PostgreSQL's own tools stop applying once the source database is a different vendor.

Per-database create, drop and upgrade scripts

The engine distribution and the engine JAR both include create, drop and upgrade SQL for each supported database type, including h2, mysql, oracle, postgres, db2 and mssql. Use the script set matching the target version, because schema differs between Flowable releases. Confirm which script set your application version expects before you generate anything, and keep the target scripts under version control with the deployment.

Naming pattern for create and drop files

Create and drop scripts follow the pattern flowable.{db}.{create|drop}.{type}.sql, where {db} is the database name and {type} identifies the table group, such as engine or history. Scripting selection by this pattern lets a pipeline pick the right files without manual lookup. Check the file names in your release, since a wrong {db} value will silently point you at another vendor's dialect.

Engine tables required, history tables optional

Engine tables hold the runtime state the engine needs to run process, case and decision work, so they are mandatory. History tables are optional and can be left out or created separately, which changes how much data you copy and how audit queries behave after cutover. Decide early whether history moves with running instances, because that choice sets the size of the data copy and the verification queries.

DBA-run production DDL

In production, database administrators often run the DDL themselves under change control, instead of letting the application create tables at startup. Agree on who runs the scripts, in which order, under which accounts and with which privileges before the cutover plan is written. Ask the DBA team to review the generated schema against your target database standards, such as tablespace placement, naming and index rules.

PostgreSQL tools apply only to PostgreSQL sources

The PostgreSQL upgrade docs describe pg_dumpall with restore and logical replication as paths for moving between PostgreSQL versions. These tools apply only when the source and target are both PostgreSQL. Logical replication works across different PostgreSQL major versions, so it fits a version change, not a vendor change.

Cross-vendor copy needs a tested extract process

Moving data from Oracle, SQL Server, DB2 or MySQL to PostgreSQL cannot use PostgreSQL's dump and replication tools, so you need a separate extract, transform and load process. Plan type mapping, sequence and identity handling, timestamp precision and character encoding, then rehearse the full copy against a restored source snapshot. Ask any partner to show the rehearsal results and the row-count and checksum reconciliation they used.

How the database cutover runs from inventory to decommission

This sequence moves a running Flowable deployment onto a new database in a controlled order, so every stage has a verified state before the next one starts. It ends with the old database retained for a defined rollback window and then decommissioned.

  1. Inventory the source database and Flowable configuration

    Record the current database type and version, the Flowable engine version, the datasource settings for each application node, and which schemas hold engine tables and optional history tables. Also list every process, case and decision deployment, custom table or view, and any scheduled job outside Flowable that writes to the same database. Confirm with your DBA which history tables are retained and which are purged, because that choice changes the volume of data copied. The step is complete when the inventory is reviewed and signed off by the application owner, the DBA and the platform team.

  2. Create the target schema from the matching DDL scripts

    On the target PostgreSQL instance, run the create scripts that match your Flowable version and the PostgreSQL database type, named in the form flowable.{db}.create.{type}.sql, from the distribution or the engine JAR. Engine tables are required; history tables are optional, so create only the history tables your retention decision needs. Database administrators often run this DDL themselves in production, so agree who runs it and under which role. The step is complete when the schema exists, the table list matches the source inventory, and no Flowable application node has been pointed at it yet.

  3. Rehearse the data copy in a non-production environment

    Copy engine and history data from the source into the empty target schema using a tool your DBA selects and tests, such as a logical copy job run against a restored snapshot of production. Time the full run and record every error, including column type conversions between the source vendor and PostgreSQL, such as timestamp precision and binary or large text columns. Rehearse until the copy completes without manual fixes. The output is a repeatable runbook with the exact commands and their order.

  4. Verify row counts and checksums on every engine table

    Compare row counts for every engine and history table between the source snapshot and the rehearsal target. For tables with stable content, compare an aggregate checksum over key columns, and review any table where counts differ by more than zero. Pay particular attention to ACT_RU_JOB, ACT_RU_TIMER_JOB and the lock columns, because stale locks copied from the source will delay or block jobs on the new node. The step is complete when every table reconciles or each difference has a documented, approved explanation.

  5. Run a parallel engine against the non-production copy

    Start the Flowable application, pointed at the rehearsal target, with the async executor enabled, and drive representative traffic through it: start instances, complete tasks, fire timers and run a sample of failed-job retries. Confirm that the engine acquires jobs, that lock owners and expiration times behave as expected, and that the application reads and writes history correctly. Check the lock behavior by stopping one node and confirming another recovers its expired locks. The step is complete when the test cases in your runbook pass and the parallel run leaves no orphaned locks.

  6. Drain in-flight jobs and timers before the switch

    Plan the cutover window so that no new instances start and no new work is accepted, then let the async executor finish jobs that are already running. Because the executor coordinates nodes through lock owners and lock expiration times stored in the database, stop the nodes gracefully and confirm that no job remains locked by a node that is shutting down. Review timers due during the window and decide whether they should fire before or after the switch. The step is complete when queries on the job tables show no locked jobs owned by the source nodes and the timer backlog is recorded.

  7. Perform the cutover and confirm the new datasource

    Take a final copy of the source data after the drain, verify its counts against the source again, and load it into the production target. Update the datasource configuration on every Flowable node, restart them in a controlled sequence, and confirm each node logs a successful connection to PostgreSQL and begins acquiring jobs. Run smoke tests on process start, task completion and a timer, and watch the job tables for failures. The step is complete when all nodes run against the new database, the smoke tests pass and the cutover record names the time and the people who approved it.

  8. Hold the rollback window and decommission the old database

    Keep the source database read-only and available for the rollback window agreed before cutover, and document the exact steps and data loss implications for returning to it. Monitor job execution, failed jobs and history completeness during this period. Once the window closes without a rollback decision, take a final backup of the source according to your retention policy, revoke application access and decommission the instance. The step is complete when the backup is verified, access is removed and the decommission is recorded in your change system.

How the async executor handles timers during the switch

The async executor is the part of a Flowable deployment most likely to be damaged by a database change, because it keeps coordination state in the database itself. According to the Flowable advanced documentation, nodes running the async executor record lock owners and lock expiration times in the database, and an expired lock lets another node pick up the job. During a database move, this means every node must stop writing to the old database before the final data copy starts. If one node keeps firing timers against the source while the target is being loaded, the copy captures a moving state, and the target may hold jobs that were already executed, or jobs whose locks still point to nodes that no longer exist.

Once the final copy is complete, start nodes against PostgreSQL only after every lock taken on the source has either been released by a clean shutdown or has passed its expiration time. Starting early risks duplicate firings, where a timer runs once on the old system and again on the new one, or lost firings, where a job is marked locked by a node that never comes back and waits until the lock expires. Both failures are silent in normal operation. Before cutover, count the rows in the job tables that are scheduled, locked and due, and record timer counts by definition, so the same counts can be compared on PostgreSQL after the copy and again after the first hour of running. Illustrative check: if 40 timers are due at the freeze point, all 40 should be present and due on the target, and none should show a lock owner from a retired node.

Confirm the exact lock and expiration behavior for your Flowable version in the Flowable advanced documentation before you set the cutover window, including the lock duration setting and how long a stopped node's locks remain valid. Those values determine how long the window must stay open after the last node stops. Document the answers in the runbook and have the operations owner sign them off, because the window length depends on your configuration, not on a general rule.

What makes the database change take longer or cost more

How does the size of the history tables affect a database change?

Larger history tables increase the time and risk of the data copy, because every historic activity, variable and job row has to be moved, verified and indexed on the target. The history tables are optional in Flowable, so the first question is whether your organization needs all of that history carried over or only the history required for open cases and audit. Reducing the volume you copy, archiving closed instances to a separate store, or agreeing a retention cut-off before the work starts all shorten the copy and the verification. Ask for the row counts per table as part of the written scope.

Does the number of process definitions and running instances change the effort?

Yes. The number of deployed process and case definitions, and the number of instances still running at cutover, determine how much data must be copied consistently and how many cases the team must test. A small set of definitions with a few hundred open instances is a simpler copy than many versions with active instances spread across them. Reduce the effort by retiring unused definitions, completing or drainning instances before the window, and confirming which definition versions must remain available. Ask the partner to list the definitions and instance counts per state in the scope.

How do custom tables and raw SQL add to the work?

Custom tables, triggers, views and raw SQL in your delegates, listeners or reporting queries are outside the vendor scripts, so each one needs a separate translation, copy rule and test. Effort rises with the number of custom objects and with how tightly they depend on one database's behavior. To reduce it, move raw SQL behind the engine API where practical, document every custom object before the work starts, and decide which ones move unchanged. Your own team can often produce this inventory, which shortens the discovery phase.

Which dialect-specific queries make a database change harder?

Queries that depend on vendor features such as proprietary date functions, locking hints, sequences, case sensitivity rules, or string and paging syntax need rewriting and retesting on the target. The Flowable engine handles its own tables through the supplied scripts, so the risk sits mainly in your code and reports. Reduce the work by listing every native query, using standard SQL where you can, and checking the MySQL precision note in the Flowable configuration docs if MySQL is one of the sources. Ask for a dialect review as a separate line in the quote.

How does the number of nodes and timers change the cutover?

More Flowable nodes sharing one database mean more coordination during the switch, because every node must stop, point to the new database and restart in the right order. The async executor uses lock owners and lock expiration times stored in the database, so timers and jobs in flight must be drained or safely handed over. Many timers due during the window raise the risk of duplicate or missed firings. To reduce the effort, plan a quiet period, pause new job creation where your design allows, and confirm the node count and timer schedule before the window is set.

How does the required cutover window length change the cost?

A shorter cutover window needs more preparation, rehearsal and automation, and often a replication-based approach, while a longer window allows a simpler stop-copy-start sequence. PostgreSQL documents logical replication between major versions as a way to reduce downtime to several seconds, but that path needs careful setup and monitoring. Your business calendar, change freeze periods and the number of dependent systems set the acceptable window. Ask for the window you need in writing and whether the quote includes rehearsals against a copy of production.

How deep should verification go, and what makes it expensive?

Verification depth is the largest variable after scope. A check of row counts and schema objects is quick, while confirming that running instances continue correctly, that timers fire once, and that reports return the same results requires scripted tests and business sign-off. Compliance-driven environments often need evidence retained for the change record. Reduce the effort by agreeing acceptance criteria and test cases up front. DeployOpen prepares the controls and evidence, but independent auditors and certification bodies decide whether your controls meet a requirement. The quote follows from a written scope that names each verification step.

What usually goes wrong in a database switch and how to prevent it

Database switches under Flowable tend to fail in the same few places: the schema is incomplete when data lands, custom SQL assumes the old vendor, timestamps and identifiers shift, and the old and new engines run at the same time. Each card below names one of these risks and the check that catches it before cutover.

Copying data before the schema is complete

Flowable ships create scripts named flowable.{db}.{create|drop}.{type}.sql for each database. Engine tables are required and history tables are optional, so a copy started before every required table exists will fail or leave gaps. Generate the target schema from the vendor scripts first, confirm every engine table exists, and only then start the data copy. Ask your DBA to record the script versions used so the schema can be reproduced.

Dialect mismatches in custom SQL

Flowable's own queries are handled per database, but custom mappers, reporting queries and delegates that call raw SQL often use vendor syntax such as Oracle sequences, SQL Server bracketed identifiers or date functions. These statements can run on the old database and fail, or return different results, on PostgreSQL. Inventory every native query in your code and configuration, rewrite them for the target dialect, and run each one against the new database in a test environment.

Timestamp precision loss

Timer due dates, job lock expiry times and history timestamps depend on the precision the source and target columns keep. A copy that truncates fractional seconds can move a timer earlier or later than planned, or make lock expiry checks behave differently. Compare column types between the source and target schemas, verify that timestamp columns keep the precision your timers need, and check a sample of due dates after the copy.

Duplicate timer firing during overlap

If the old and new deployments both run the async executor against their own databases, or both point at the same data during a transition, timers and asynchronous jobs can fire twice or be missed. Flowable coordinates nodes through lock owners and lock expiration times in the database, so the two engines must never share a live job table without that coordination. Stop the async executor on the source before the final delta copy, and confirm that no job is locked by an engine you have retired.

Missing sequences and identity behavior

Oracle sequences, SQL Server identity columns and PostgreSQL sequences do not transfer automatically when rows are copied with their original IDs. If the sequence restarts below the highest copied ID, new inserts collide with migrated rows or fail with duplicate key errors. After the copy, set each sequence or identity to the maximum migrated value, and test that a new process instance receives a fresh ID.

Rollback that was never tested

A cutover plan without a tested way back leaves the team stuck if the new database shows problems in the first hours. Rollback needs the source database kept intact and writable only by the old deployment, plus a way to replay or reconcile transactions made on the target. Rehearse the full cutover and the return to the source in a staging environment, and time each step so the cutover window is set from measured results.

What your team must provide for the move

Your team must provide working access to the source and target databases, a change window agreed with the business, and a named DBA who owns the DDL. Flowable ships create, drop and upgrade scripts per database, named flowable.{db}.{create|drop}.{type}.sql, and production DDL is often run only by database administrators. Confirm early who will execute the target schema scripts, whether that person has rights to create tables and indexes in the target account, and whether history tables are in scope or only engine tables. The DBA decides how the target schema is created, and DeployOpen does not run production DDL without that person's approval.

Application owners must confirm two things that the database itself cannot reveal. The first is any custom SQL, such as reporting queries, custom mappers or stored procedures that read Flowable tables, because those statements may depend on dialect-specific behavior. The second is the list of timers and asynchronous jobs that must survive the cutover, so the team can decide whether to drain the async executor before the copy or let in-flight work resume on the new database. Provide representative test data, including a copy of active process instances, and agree the verification criteria in writing, such as row counts, job counts and a set of end-to-end process paths. Your sign-off on those criteria defines what a successful move means.

DeployOpen plans and runs the technical work inside your own cloud accounts, data centers or air-gapped networks, so credentials, data copies and logs stay under your control. Your team keeps approval over every production change, including the cutover decision, the rollback point and the go or no-go call at the end of the window. Ask for a written scope that names who performs each step, which environments are used for rehearsals, and how a failed verification is handled before the change window opens.

Questions teams ask before changing a Flowable database

Can we change the database under Flowable without rebuilding the application?

Yes, in most cases the change is a database move rather than a new application, but it is not a configuration toggle. Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server, and the engine tables must be created in the target database from the vendor-specific scripts before any data moves. The application then points at the new JDBC connection, and the data copy and cutover decide whether the move is clean. Confirm the exact Flowable version you run, because the scripts and supported combinations are tied to that version.

How long does the cutover take?

The cutover window depends on how much data the engine holds, how many jobs and timers are in flight, and how much downtime your business accepts. Flowable itself does not publish a duration for this work, so treat any number from a vendor or partner as a claim to test against your own copy. Ask for a rehearsal on a production-sized copy and measure the copy and reconciliation steps. Your window must also cover pausing the async executor so no job runs against a half-copied database.

What drives the cost of a database change?

Cost follows the work, not the database name. The main drivers are the number of Flowable engines and schemas, whether history tables are kept, data volume, the number of custom delegates and SQL queries that assume the old vendor's dialect, the number of environments to rehearse in, and how strict the cutover window is. Some costs are one-time, such as design, rehearsal and cutover support. Others recur if you keep a parallel environment or need ongoing database operations after go-live. Ask any partner to split the quote into those groups.

Can our own DBA do this work?

Often yes, if they have done schema migrations and can test Flowable's behavior. Flowable notes that production DDL is often run only by database administrators, so your DBA will likely execute the create scripts. The harder parts are the data copy, checking that timestamps and identifiers survive the move, verifying the async executor's lock handling, and proving that counts and in-flight work match before and after. Decide early who owns each step and who signs off on the cutover.

Does Flowable's in-place migration from Camunda or Activiti cover a database change?

No. Flowable's in-place migration path for Camunda 7 and Activiti data addresses moving those engines' active instances and history into Flowable. It does not change the database vendor under a running Flowable deployment. If you are on Camunda or Activiti and also changing databases, plan the two moves as separate steps with their own testing, and confirm the sequence with your engineers before you commit to a window.

How do in-flight jobs and timers behave during the move?

The async executor keeps lock owners and lock expiration times in the database, so the nodes that run jobs depend on the same tables you are moving. If nodes keep running during the copy, jobs can execute against partial data or be locked against the old database. Plan to stop all engine nodes, or drain them, before the final copy, confirm no locks are held, and then start the new nodes against the target. Check that timers scheduled for the cutover window fire once and only once after the restart.

What should we ask a partner for in a quote?

Ask for a written scope that names the Flowable version, the source and target databases and versions, the engines and schemas in scope, whether history tables move, and the environments to rehearse in. Ask how the data copy will be verified, how in-flight jobs and timers will be handled, the rollback plan and its time limit, and what is delivered at each step. Ask who runs the production cutover and who is on call afterward. Compare quotes on those items, not on a headline figure.

Which target database versions should we consider?

Pick a target version that your vendor and your Flowable version both support, and that is still in its support window when you go live. For PostgreSQL, the versioning policy lists the supported majors and their end dates, so check the current table before you choose. Also confirm that your Flowable release and JDBC driver support the target version, because support is set by the combination you run.

How DeployOpen scopes and delivers a Flowable database change

DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside the client's own infrastructure, so a database change is run in your cloud accounts, data centers or air-gapped network. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

  • Inventory the current Flowable version, enabled engines, history tables and the source database type and version.
  • Agree in writing which target database and version the engine will run on, and who owns each cutover step.
  • Define the in-flight job and timer policy, the acceptable cutover window and the rollback point before any work starts.
  • Confirm who will run DDL, since many production teams limit schema creation to database administrators.

How we build

  • Create the target schema from the vendor create scripts for the chosen database, then compare it with the source table layout.
  • Copy engine and any history tables, then reconcile row counts and key data between source and target.
  • Test the application against the target database in a staging copy, including async executor behavior and lock recovery.
  • Document the connection, driver and datasource configuration changes needed for each environment.

How we hand over

  • Provide the cutover runbook with ordered steps, verification queries, go or no-go checks and the rollback procedure.
  • Record the test evidence, reconciliation results and configuration diffs as part of the delivered documentation.
  • Walk through the operating model with your platform and database teams, including monitoring and backup of the new database.
  • Hand over any scripts or pipeline changes so your team can rerun the process for later environments.

How we support

  • Support after cutover is available as a retainer, covering incidents, patching and follow-up questions on the moved database.
  • Scope any post-cutover changes, such as a later database major version upgrade, as a separate written engagement.
  • Ask for a named support contact, response expectations and escalation path in the written scope before signing.
  • Continuous security testing of the application and its APIs can be added alongside the support arrangement.

Sources and further reading

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.