Issue running Kill Bill DB migrations with Flyway CLI after removing Flyway wrapper (0.24.12 → 0.24.16)

[Ahmed Elwan]

Hello Kill Bill team,

While upgrading Kill Bill from 0.24.12 to 0.24.16, we ran into an issue related to database migrations after the Flyway wrapper was removed starting from 0.24.15 (PR: https://github.com/killbill/killbill/pull/2094).

The official documentation recommends executing migrations using Flyway CLI:
https://docs.killbill.io/latest/how-to-upgrade-the-database#_step_2_execute_the_migrations

We attempted to follow this approach by replacing the removed Flyway wrapper with Flyway CLI (Community Edition).

---

Environment

• Kill Bill upgrade: 0.24.12 → 0.24.16

• Database: MariaDB 10.11

• Flyway CLI versions tested:

  • 9.16.3

  • 11.x (11.15 / 11.20)

• Migrations downloaded via:

  kpm migrations killbill killbill-0.24.12  killbill-0.24.16

---

Issue Observed:

When running Flyway CLI against the Kill Bill migrations directory:

flyway \ -url=jdbc:mysql://db:3306/killbill \ -user=root \ -password=***** \ -table=killbill_schema_history \ -locations=filesystem:/var/lib/killbill/migrations/killbill \ migrate

Flyway fails with the following error:

ERROR: Found more than one migration with version 20250917094123 Offenders: -> V20250917094123__payments_payment_methods_index.sql -> V20250917094123__bundles_index.sql

This happens because multiple Kill Bill core migrations share the same timestamp-based version, which Flyway CLI rejects.

---

Key Question

Since:

• Flyway CLI does not allow duplicate migration versions

• Kill Bill core migrations contain duplicate timestamp versions

• The Flyway wrapper was removed in 0.24.15

• The documentation still recommends Flyway CLI

👉 What is the officially supported way to run Kill Bill core DB migrations post-0.24.15?

Specifically:

• Should migrations still be executed only via Kill Bill startup / KPM, and not raw Flyway CLI?

• Is there a recommended Flyway configuration or wrapper replacement that tolerates duplicate timestamps?

• Or should Flyway CLI only be used for plugin databases, not Kill Bill core?

---

Summary

• Flyway CLI (all tested versions) fails due to duplicate migration versions in Kill Bill core

• This behavior is consistent across Flyway 9.x and 11.x

• Documentation suggests Flyway CLI, but in practice it conflicts with Kill Bill migrations

We’d appreciate clarification on the intended and supported migration path after the Flyway wrapper removal.

Thanks in advance for your guidance.

[Reshma Bidikar]

Hello,

You are right, the Flyway wrapper is indeed deprecated from KB 0.24.15.  We will update the migration document. For now, can you run the SQL statements directly on top of the database?

Regards,

Reshma