ADR: DBMigrationStrategy: Job-Based Schema Migration Design

[mathecruz]

This pull request aims to proposal a solution to solve the #25.

[ricardozanini]

Additionally, we should:

1. Create a new LogicFlowDBMigration type that will reconcile the objects to deploy the job
2. The status field of this new CR will reflect the actual DB state (version, last modified time, etc)
3. It should be one CR per platform/runtime since it will target specific schemas
4. Think on how the matrix of schemas/components will work. For example, we can have a db migration per runtime, per platform, distributed accross 3 components (runtime, DI, and Quartz). Perhaps the migration strategy should be tied only to the platform, not runtime to not overengineer the solution.

[ricardozanini]

@mcruzdev any updates?

[mathecruz]

Hi @ricardozanini, sorry. This one currently is blocked by quarkiverse/quarkus-flow#895 which needs to be accepted and implemented.

[mathecruz]

@ricardozanini the ADR there are 3 steps, we can implement step-by-step. Once it merged, I can create all issues and to track all the whole progress through issues. Basically we need:

• Step 1: runtime schema migration
• Step 2: Publish data index migration extension
• Step 3: Publish quarkus-flow-db-migration extension

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical design and safety issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 7 · 5

Open (12)

• Fail closed when multiple Platforms exist · New
• Increase PersistenceOptionsSpec MaxProperties for MigrationImage · New
• Restrict and validate migration image and script inputs · New
• Prevent rerunning garbage-collected terminal migration Jobs · New
• Serialize Jobs when replacing an active migration hash · New
• Resolve effective Runtime persistence configuration before migration gating · New
• Stop existing Deployments while migration is pending · New
• Persist migration failure details in status · New
• Clean up migrations when strategy changes · New
• Watch LogicDbMigration status changes from the Platform controller · New
• Skip deployment-dependent lease reconciliation when Deployment is absent · New
• Watch Platform migration changes from the Runtime controller · New

What changed in this PR

This PR proposes a platform-owned, Job-based database migration architecture for runtime, Data Index, and Quartz schemas.

Changes:

• Defines migration strategies and ownership semantics.
• Proposes the LogicDbMigration CRD, controller, Job lifecycle, status, and RBAC.
• Adds runtime migration gating and outlines phased delivery and testing.

File	Review summary
adr/​implementation/​db-migration-strategy.md	7 critical and 5 moderate issues remain, including incomplete effective-configuration handling, unsafe Deployment and Job lifecycle behavior, missing watches and cleanup paths, CRD validation/status gaps, authorization concerns, concurrent migrations, and ambiguous Platform resolution.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.