WIP: Replace Flyway with Liquibase for database-agnostic schema management #1

Draft

binarymelon wants to merge 1 commit from feature/liquibase-migration into develop

binarymelon commented

2026-03-08 13:37:04 -03:00

(Migrated from github.com)

Add spring-boot-starter-liquibase dependency alongside existing Flyway
Replace FlywayConfig with DatabaseMigrationConfig that auto-detects flyway_schema_history and runs legacy catch-up before Liquibase
Create baseline schema changelog (67 tables, indexes, constraints) with onFail:MARK_RAN preconditions for safe existing-DB upgrades
Create seed data changelog for app_settings and task_cron_configuration
Handle virtual column (book_file.alt_format_current_hash) with database-specific changesets for MariaDB and PostgreSQL
Update all test classes to disable both Flyway and Liquibase
Disable Flyway auto-config (legacy catch-up handled by custom bean)

📝 Description

Linked Issue: Fixes #

Required. Every PR must reference an approved issue. If no issue exists, open one and wait for maintainer approval before submitting a PR. Unsolicited PRs without a linked issue will be closed.

🏷️ Type of Change

Bug fix
New feature
Enhancement to existing feature
Refactor (no behavior change)
Breaking change (existing functionality affected)
Documentation update

🔧 Changes

🧪 Testing (MANDATORY)

PRs without this section filled out will be closed. "Tests pass" or "Tested locally" is not sufficient. You must provide specifics.

Manual testing steps you performed:

Regression testing:

Edge cases covered:

Test output:

Backend test output (./gradlew test)

PASTE OUTPUT HERE

Frontend test output (ng test)

PASTE OUTPUT HERE

📸 Screen Recording / Screenshots (MANDATORY)

Every PR must include a screen recording or screenshots showing the change working end-to-end in a running local instance (both backend and frontend). This means you must have actually built, run, and tested the code yourself. PRs without visual proof will be closed without review.

✅ Pre-Submission Checklist

All boxes must be checked before requesting review. Incomplete PRs will be closed without review. No exceptions.

This PR is linked to an approved issue
Code follows project backend and frontend conventions
Branch is up to date with develop (merge conflicts resolved)
I ran the full stack locally (backend + frontend + database) and verified the change works
Automated tests added or updated to cover changes (backend and frontend)
All tests pass locally and output is pasted above
Screen recording or screenshots are attached above proving the change works
PR is a single focused change (one bug fix OR one feature, not multiple unrelated changes)
PR is reasonably scoped (PRs over 1000+ changed lines will be closed, split into smaller PRs)
No unsolicited refactors, cleanups, or "improvements" are bundled in
Flyway migration versioning is correct (if schema was modified)
Documentation PR submitted to booklore-docs (if user-facing changes)

🤖 AI-Assisted Contributions

If any part of this PR was generated or assisted by AI tools (Copilot, Claude, ChatGPT, etc.), all items below are mandatory. You are fully responsible for every line you submit. "The AI wrote it" is not an excuse, and AI-generated PRs that clearly haven't been reviewed are the #1 reason PRs get closed.

I have read and understand every line of this PR and can explain any part of it during review
I personally ran the code and verified it works (not just trusted the AI's output)
PR is scoped to a single logical change, not a dump of everything the AI suggested
Tests validate actual behavior, not just coverage (AI-generated tests often assert nothing meaningful)
No dead code, placeholder comments, TODOs, or unused scaffolding left behind by AI
I did not submit refactors, style changes, or "improvements" the AI suggested beyond the scope of the issue

💬 Additional Context (optional)

Migrate from Flyway to Liquibase using YAML-format changelogs targeting MariaDB, PostgreSQL, and SQLite. Existing Flyway migrations are retained as a catch-up mechanism for users upgrading from older Booklore versions. - Add spring-boot-starter-liquibase dependency alongside existing Flyway - Replace FlywayConfig with DatabaseMigrationConfig that auto-detects flyway_schema_history and runs legacy catch-up before Liquibase - Create baseline schema changelog (67 tables, indexes, constraints) with onFail:MARK_RAN preconditions for safe existing-DB upgrades - Create seed data changelog for app_settings and task_cron_configuration - Handle virtual column (book_file.alt_format_current_hash) with database-specific changesets for MariaDB and PostgreSQL - Update all test classes to disable both Flyway and Liquibase - Disable Flyway auto-config (legacy catch-up handled by custom bean) ## 📝 Description  **Linked Issue:** Fixes # > **Required.** Every PR must reference an approved issue. If no issue exists, [open one](https://github.com/booklore-app/booklore/issues/new) and wait for maintainer approval before submitting a PR. Unsolicited PRs without a linked issue will be closed. ## 🏷️ Type of Change - [ ] Bug fix - [ ] New feature - [ ] Enhancement to existing feature - [ ] Refactor (no behavior change) - [ ] Breaking change (existing functionality affected) - [ ] Documentation update ## 🔧 Changes  - ## 🧪 Testing (MANDATORY) > **PRs without this section filled out will be closed.** "Tests pass" or "Tested locally" is not sufficient. You must provide specifics. **Manual testing steps you performed:**  1. 2. 3. **Regression testing:**  - **Edge cases covered:**  - **Test output:**  <details> <summary>Backend test output (<code>./gradlew test</code>)</summary> ``` PASTE OUTPUT HERE ``` </details> <details> <summary>Frontend test output (<code>ng test</code>)</summary> ``` PASTE OUTPUT HERE ``` </details> ## 📸 Screen Recording / Screenshots (MANDATORY) > Every PR must include a **screen recording or screenshots** showing the change working end-to-end in a running local instance (both backend and frontend). This means you must have actually built, run, and tested the code yourself. PRs without visual proof will be closed without review.  --- ## ✅ Pre-Submission Checklist > **All boxes must be checked before requesting review.** Incomplete PRs will be closed without review. No exceptions. - [ ] This PR is linked to an approved issue - [ ] Code follows project [backend and frontend conventions](../CONTRIBUTING.md#backend-conventions) - [ ] Branch is up to date with `develop` (merge conflicts resolved) - [ ] I ran the full stack locally (backend + frontend + database) and verified the change works - [ ] Automated tests added or updated to cover changes (backend **and** frontend) - [ ] All tests pass locally and output is pasted above - [ ] Screen recording or screenshots are attached above proving the change works - [ ] PR is a single focused change (one bug fix OR one feature, not multiple unrelated changes) - [ ] PR is reasonably scoped (PRs over 1000+ changed lines will be closed, split into smaller PRs) - [ ] No unsolicited refactors, cleanups, or "improvements" are bundled in - [ ] Flyway migration versioning is correct _(if schema was modified)_ - [ ] Documentation PR submitted to [booklore-docs](https://github.com/booklore-app/booklore-docs) _(if user-facing changes)_ ### 🤖 AI-Assisted Contributions > **If any part of this PR was generated or assisted by AI tools (Copilot, Claude, ChatGPT, etc.), all items below are mandatory.** You are fully responsible for every line you submit. "The AI wrote it" is not an excuse, and AI-generated PRs that clearly haven't been reviewed are the #1 reason PRs get closed. - [ ] I have read and understand every line of this PR and can explain any part of it during review - [ ] I personally ran the code and verified it works (not just trusted the AI's output) - [ ] PR is scoped to a single logical change, not a dump of everything the AI suggested - [ ] Tests validate actual behavior, not just coverage (AI-generated tests often assert nothing meaningful) - [ ] No dead code, placeholder comments, `TODO`s, or unused scaffolding left behind by AI - [ ] I did not submit refactors, style changes, or "improvements" the AI suggested beyond the scope of the issue --- ## 💬 Additional Context _(optional)_

This pull request is marked as a work in progress.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feature/liquibase-migration:feature/liquibase-migration

git switch feature/liquibase-migration

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch develop

git merge --no-ff feature/liquibase-migration

git switch feature/liquibase-migration

git rebase develop

git switch develop

git merge --ff-only feature/liquibase-migration

git switch feature/liquibase-migration

git rebase develop

git switch develop

git merge --no-ff feature/liquibase-migration

git switch develop

git merge --squash feature/liquibase-migration