Liquibase migration from camunda

Development
1

Hello,

I have a question regarding how to approach the database migration from camunda to operaton. Currently we have a camunda 7.23 server running embedded with Spring Boot that uses liquibase migrations. The liquibase changelog we are using is the one included in camunda, the one bundled in camunda: “org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml”. However, when changing to the one of operaton (“org/operaton/bpm/engine/db/liquibase/operaton-changelog.xml”), all the sql files changes their name and thus, liquibase considers them as new migrations. So, at the startup, liquibase will try to run all migrations and it will obviously fails as those were already executed by using the camunda changelog.

Did someone encounter this issue? Is there a solution bundled in operaton (I searched for sql files but I have not found a migration to handle this scenario)?

P.S. We are using postgres and we do have a workaround sql migration that simply modifies the liquibase table:

UPDATE public.databasechangelog
SET filename='org/operaton/bpm/engine/db/liquibase/operaton-changelog.xml', md5sum=''
WHERE filename='org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml';

Not really a great solution since it changes the history of the liquibase table, but we wanted to know if there was an official solution by Operaton.

2

Hi @tangtang.zhou,

thanks for reaching out, I will look into this. You wrote that you changed the liquibase changelog to the one of Operaton, do you have an additional, manual Liquibase configuration? If so, are you able to post this here?

Usually when using Operaton you don’t have to interact with Liquibase manually. We talked to several other projects who upgraded to Operaton without seeing this error, I’ll try and reach out to them to confirm this.

3

Hello @javahippie,

Thanks for the quick response. We do have a manual liquibase changelog outside the camunda one. It was basically added to introduce liquibase (at first we did not use any migration). So it simply contains sql migration that modifies the liquibase table. Here is the changelog with one sql example:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                   http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <!--This files already created before liquibase integration-->
    <!--Setting baseline-->
    <changeSet author="Camunda" id="setup-7.16">
        <sqlFile path="liquibase/changelog/db.files/camunda_7.16_baseline.sql"/>
    </changeSet>

    <changeSet author="Camunda" id="update-7.16-to-7.17">
        <sqlFile path="liquibase/changelog/db.files/camunda_7.16_to_7.17.sql"/>
    </changeSet>

    <changeSet author="Camunda" id="update-7.17-to-7.18">
        <sqlFile path="liquibase/changelog/db.files/camunda_7.17_to_7.18.sql"/>
    </changeSet>

    <changeSet author="Camunda" id="update-7.18-to-7.19">
        <sqlFile path="liquibase/changelog/db.files/camunda_7.18_to_7.19.sql"/>
    </changeSet>

    <changeSet author="Camunda" id="update-7.19-to-7.20">
        <sqlFile path="liquibase/changelog/db.files/camunda_7.19_to_7.20.sql"/>
    </changeSet>

    <changeSet author="Camunda" id="update-7.20-to-7.21">
        <sqlFile path="liquibase/changelog/db.files/camunda_7.20_to_7.21.sql"/>
    </changeSet>
</databaseChangeLog>

Sql example “camunda_7.16_baseline.sql”:

INSERT INTO public.databasechangelog(
    id,
    author,
    filename,
    dateexecuted,
    orderexecuted,
    exectype,
    md5sum,
    description,
    tag,
    liquibase,
    deployment_id
)
VALUES(
    '7.16.0-baseline',
    'Camunda',
    'org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml',
    '2024-08-09 01:23:07.218985',
    0,
    'EXECUTED',
    '9:5e6ef4184be45cf309cb3708cad2b8a4',
    'sqlFile path=baseline/liquibase.postgres.create.engine.sql; sqlFile path=baseline/liquibase.postgres.create.history.sql; sqlFile path=baseline/liquibase.postgres.create.identity.sql; sqlFile path=baseline/liquibase.postgres.create.case.engine.sql;...',
    null,
    '4.29.0',
    '0'
),
(
    '7.16.0-tag',
    'Camunda',
    'org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml',
    '2024-08-09 01:23:07.218985',
    0,
    'EXECUTED',
    '9:b65ef039a8fbef1d30339cd77e1387d9',
    'tagDatabase',
    '7.16.0',
    '4.29.0',
    '0'
);
4

Hi @tangtang.zhou,

did you already try updating the Liquibase tracking tables manually?

What usually works as a one-time fix is to baseline the new changelog with changelogSync. That just writes the missing entries into DATABASECHANGELOG, so Liquibase thinks everything is applied already. No schema changes.

Safer way is to first run changelogSyncSQL, check the statements, then run changelogSync. After that a quick clearCheckSums helps to refresh the hashes.

Haven’t tested it yet with Operaton specifically, but we used the same approach in other projects and it worked fine. Was the first thing that came to my mind when reading your issue.

5

Hello @ungerts,

We did not consider a manual approach. Ideally, we want an update that is automatic and requires no manual steps. I guess it might be possible to create a kubernetes job that applies all those liquibase commands, but it seems to be a more complicated approach than simply adding a migration that edits directly the table of liquibase. Thanks for the suggestion, we will think about it!

6

Thanks for providing your config!

I will try and reproduce your error, ideally I would not expect users to manually clean up checksums during upgrades. I’ll get back to you soon!

1 Like
7

I had time to create a PoC repo for the migration issue with Liquibase. Here is the link: GitHub - tangtang95/camunda-to-operaton-example: PoC to migrate from camunda to operaton with Liquibase

EDIT: If you want I can provide also a branch with the workaround liquibase changelog mentioned in the first message

8

Hello @javahippie,

Were you able to replicate the issue using my PoC repo?

9

Hi @tangtang.zhou, sorry for the late reply.

I was able to reproduce the error, and am currently debugging what can be done. What I can say is that if a Spring Boot application does not have its own Liquibase configuration, the error does not happen.

In projects I have done in the past using Liquibase we set the “logicalFilePath” in the migrations themselves to keep this from happening. I’m currently checking how this could be applied retroactively without changing the files and will get back to you.

10

I think I solved the problem for your setup.

First, I created a new Changelog in src/main/resources/custom-changelog.xml:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="
          http://www.liquibase.org/xml/ns/dbchangelog
          http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <include file="org/operaton/bpm/engine/db/liquibase/operaton-changelog.xml"
             relativeToChangelogFile="false"
             logicalFilePath="org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml"/>

</databaseChangeLog>

This includes the Operaton Changelog and sets the old Camunda filepath as logicalFilePath.

The Liquibase config then needs to be adapted like this to refresh the checksums (can be removed after an initial deployment) and to reference the new changeset:

@Configuration
@ConditionalOnProperty( value = "spring.liquibase.enabled", havingValue = "true")
public class LiquibaseConfiguration {

    private static final String CAMUNDA_CHANGELOG ="classpath:custom-changelog.xml";

    @Bean
    public SpringLiquibase liquibaseUpdateChangelog(DataSource dataSource) {
        SpringLiquibase liquibase = new SpringLiquibase();
        liquibase.setDataSource(dataSource);
        liquibase.setChangeLog(CAMUNDA_CHANGELOG);
        liquibase.setClearCheckSums(true);

        return liquibase;
    }
}

The changes need to be done before the application was started with the new Operaton Classnames and resources.

Can you verify this solution, too?

11

Thanks for the help @javahippie,

The new changelog solution does work and it is much cleaner than doing a migration to solve the issue. However, I would not expect that clearing checksums is needed because I expect the sql files to be unchanged from the camunda 7 repo. Also I noticed that bumping to the operaton beta-5 version have required us to clear the checksums again because some sql files have been changed from beta-4 to beta-5 and therefore the checksums were different.

Anyway other than the checksums issue, I think the solution with the new changelog is a good one. Thanks for the help again!

1 Like
12

I was suprised by having to adapt the checksums, too. Maybe there is still a small error in my thinking? If you find a solution or fix, I’d be happy to know about it.

The change from beta-4 to beta-5 was unfortunate, but from now on (and of course after adapting all changes from 7.24) this won’t happen again, when we move to a more stable release version.

Thanks again for trying the migration and contributing here in the forums!

13

Since sql files has already been changed, I don’t think reverting them is a good idea otherwise the update from beta-5 to the next version will require another clear checksum. However I did saw a way to add valid checksum to a changeset:

<changeSet id="1" author="example">
   <validCheckSum>8:b4fd16a20425fe377b00d81df722d604</validCheckSum>
   <addColumn tableName="my_table">
       <column name="my_column" type="BIGINT"/>
   </addColumn>
</changeSet>

In this way you can add the camunda checksum as a valid one in the operator-changelog. After adding all of these, I expect that there should be no need for clear checksums when migrating from camunda to operaton

1 Like
14

Hello,

I am also currently doing this migration from Camunda to Operaton (because I need Spring Boot 4 compatibility).

The information you wrote here was really helpful so thank you.

I am currently stuck somewhere else though.

I already have a custom-changelog.xml which is am using so I just set

<include file="org/operaton/bpm/engine/db/liquibase/operaton-changelog.xml"
         relativeToChangelogFile="false"
         logicalFilePath="org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml"/>

And also in the configuration

spring.liquibase.clear-checksums = true

The problem now is that for the migration 7.23 to 7.24 in Operaton I get Author permission issues basically

liquibase.changelog : ChangeSet org/camunda/bpm/engine/db/liquibase/camunda-changelog.xml::7.23-to-7.24::Operaton encountered an exception.

liquibase.exception.DatabaseException: ORA-00001: unique constraint (SYS_C007101) violated

https://docs.oracle.com/error-help/db/ora-00001/` [Failed SQL: (1) insert into ACT_GE_SCHEMA_LOG values (‘1300’, CURRENT_TIMESTAMP, ‘7.24.0’)]`

So what I did was, I created a simple update script for that specific file to change the Author before doing the migration and it works, eventually.

The problem? PODs are doing 1 restart before picking it up correctly.

Is there maybe another way to do this to avoid the restart?

Maybe am I missing something.

Thank you! Much appreciated

15

Sorry I did not have faced the situation before. But given the changelogs are already final and must not be changed after the fact, I think the only thing we can do is document this. If you have a concrete proposal for a documentation change consider providing a PR to the documentation repository. Other users and we would be thankful.

16

Hello, no problem. @kthoms

Once I see if my before-camunda.xml (operaton) with custom SQL fix works properly, I will let you know of the steps and issues I encountered in detail.

Thank you!

17

Hello @kthoms ,

I have it running on PRD since yesterday, once I get back from holiday, on the 24th of August, I will leave the steps I did to make everything work properly given the current context.

As mentioned I had 2 script changes that I had to do so, I will leave the database CHANGELOG situation before and after, maybe it will help and also with the proper explanations on why I went this route to make it run properly.

If you need further assistance, please let me know.

Much appreciated, thank you!

Liquibase migration from Camunda, already on version 7.24.0
Operaton 2.1.4 and 2.2.0-M3 released