fix(db): add explicit collation for icon map migration

[alexhb1]

Description

The icons migration can fail with older databases with tables generated under a different collation (unicode_ci). This fixes the issue with explicit general_ci collations for the icon mapping.

This patches the existing v144 migration. There's no impact on existing / working users, and it should fix any issues for people who have updated and experienced issues, as well as anyone updating normally.

Linked Issue

Fixes #1943

Changes

Add explicit general_ci collation for the icon maps instead of inheriting the user's shelf/magic shelf table collation.

Manual Testing Steps

Migrate with a shelf/magic shelf table set to unicode_ci, confirm the migration works without issue.

Screenshots (Optional)

N/A

Additional Context (Optional)

N/A

AI Disclosure

N/A

Checklist

• This PR links and implements an accepted issue.
• This PR is a single focused change.
• There are new or updated tests validating this change.
• I ran just ui check and just api check.
• I have added screenshots if there were any UI changes.
• I have disclosed any AI usage as per the organization AI Policy above.
• I understand all of my submitted changes.

Summary by CodeRabbit

• Bug Fixes
  • Improved icon migration handling to ensure consistent icon updates across supported languages and character sets.
  • Reduced the likelihood of mismatched or missing icons during the migration process.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 732439ef-bddb-487f-82b0-078e599a1195

📥 Commits

Reviewing files that changed from the base of the PR and between 7bcb29a and 57ef8d8.

📒 Files selected for processing (1)

• backend/src/main/resources/db/migration/V144__Migrate_entity_icons_to_lucide.sql

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: Analyze (java-kotlin)
• GitHub Check: Frontend Lint Threshold Check

⚠️ CI failures not shown inline (2)

GitHub Actions: CI - Validate / 2_Flyway Migration Check _ Flyway DB Migration Preview.txt: fix(db): add explicit collation for icon map migration

Conclusion: failure

View job details

##[group]Run echo "Applying new migrations from head ref (${HEAD_REF})..."
 �[36;1mecho "Applying new migrations from head ref (${HEAD_REF})..."�[0m
 �[36;1mdocker run --network host \�[0m
 �[36;1m  -v ${GITHUB_WORKSPACE}:/flyway/sql \�[0m
 �[36;1m  flyway/flyway:12.1.0 \�[0m
 �[36;1m  -url=jdbc:mariadb://127.0.0.1:3306/booklore_test \�[0m
 �[36;1m  -user=root -*** \�[0m
 �[36;1m  -locations=filesystem:/flyway/sql/backend/src/main/resources/db/migration \�[0m
 �[36;1m  migrate�[0m
 shell: /usr/bin/bash -e {0}
 env:
   GITHUB_WORKSPACE: /home/runner/work/grimmory/grimmory
   HEAD_REF: 57ef8d83420d80989fa8b0df7b1d084bdae5a792
 ##[endgroup]
 Applying new migrations from head ref (57ef8d83420d80989fa8b0df7b1d084bdae5a792)...
 Flyway OSS Edition 12.1.0 by Redgate
 See release notes here: https://rd.gt/416ObMi
 Database: jdbc:mariadb://127.0.0.1:3306/booklore_test (MariaDB 10.6)
 ERROR: Validate failed: Migrations have failed validation
 Migration checksum mismatch for migration version 144
 -> Applied to database : -275841425
 -> Resolved locally    : 1771524574
 Either revert the changes to the migration, or run repair to update the schema history.
 Need more flexibility with validation rules? Learn more: https://rd.gt/3AbJUZE
 ##[error]Process completed with exit code 1.

---

GitHub Actions: CI - Validate / Flyway Migration Check _ Flyway DB Migration Preview: fix(db): add explicit collation for icon map migration

Conclusion: failure

View job details

##[group]Run echo "Applying new migrations from head ref (${HEAD_REF})..."
 �[36;1mecho "Applying new migrations from head ref (${HEAD_REF})..."�[0m
 �[36;1mdocker run --network host \�[0m
 �[36;1m  -v ${GITHUB_WORKSPACE}:/flyway/sql \�[0m
 �[36;1m  flyway/flyway:12.1.0 \�[0m
 �[36;1m  -url=jdbc:mariadb://127.0.0.1:3306/booklore_test \�[0m
 �[36;1m  -user=root -*** \�[0m
 �[36;1m  -locations=filesystem:/flyway/sql/backend/src/main/resources/db/migration \�[0m
 �[36;1m  migrate�[0m
 shell: /usr/bin/bash -e {0}
 env:
   GITHUB_WORKSPACE: /home/runner/work/grimmory/grimmory
   HEAD_REF: 57ef8d83420d80989fa8b0df7b1d084bdae5a792
 ##[endgroup]
 Applying new migrations from head ref (57ef8d83420d80989fa8b0df7b1d084bdae5a792)...
 Flyway OSS Edition 12.1.0 by Redgate
 See release notes here: https://rd.gt/416ObMi
 Database: jdbc:mariadb://127.0.0.1:3306/booklore_test (MariaDB 10.6)
 ERROR: Validate failed: Migrations have failed validation
 Migration checksum mismatch for migration version 144
 -> Applied to database : -275841425
 -> Resolved locally    : 1771524574
 Either revert the changes to the migration, or run repair to update the schema history.
 Need more flexibility with validation rules? Learn more: https://rd.gt/3AbJUZE
 ##[error]Process completed with exit code 1.

🧰 Additional context used

📓 Path-based instructions (2)

backend/src/main/resources/db/migration/*.sql

📄 CodeRabbit inference engine (AGENTS.md)

Add Flyway migrations as new files named V__.sql

Files:

• backend/src/main/resources/db/migration/V144__Migrate_entity_icons_to_lucide.sql

**/*

⚙️ CodeRabbit configuration file

**/*: This project is being developed using current and future-facing technologies:

• Java 25 with --enable-preview (preview features are INTENTIONAL and encouraged)
• Spring Boot 4 (latest major version, check APIs accordingly)
• Jackson 3 (new package: tools.jackson.* instead of com.fasterxml.jackson.*)
• Hibernate 7.3.x (Jakarta Persistence 3.2, new APIs; avoid deprecated Hibernate 5/6 patterns)
• Angular 21 (signals-based reactivity, no NgModules unless legacy)

Grimmory Internal Tools

• epub4j and pdfium4j are our own internal tools developed by the Grimmory team.
• Always verify behavior and API changes against the upstream repositories:
  • epub4j: https://github.com/grimmory-tools/epub4j
  • pdfium4j: https://github.com/grimmory-tools/pdfium4j
• If you encounter issues with these libraries, check if a fix exists in the upstream grimmory-tools organization.

Metadata Standards and Compliance

• For all metadata writing and parsing logic, double-check against Dublin Core and ANSI standards to ensure perfect official compliance.
• We strictly follow the widespread and official XML-compliant methods for EPUB2, EPUB3, CBX, and PDF formats.

General Java and Spring rules

• ALWAYS prefer modern, idiomatic Java 25 constructs over legacy patterns.
• Preview features (--enable-preview) are enabled and intentional; do NOT flag them as risky unless there is a concrete runtime issue.
• Prefer: records, sealed classes/interfaces, pattern matching (switch expressions, instanceof), structured concurrency (StructuredTaskScope), scoped values, string templates, unnamed patterns/variables.
• Prefer virtual threads (Thread.ofVirtual(), Executors.newVirtualThreadPerTaskExecutor()) over platform threads for I/O-bound work.
• Prefer the new Sequenced Collections API (SequencedCollection, SequencedMap) where applicable.
• Prefer var for local variables when the type is obvious from context.
• Use stream().toList() instead of stream().collect(Collectors.toList()) for imm...

Files:

• backend/src/main/resources/db/migration/V144__Migrate_entity_icons_to_lucide.sql

🔇 Additional comments (2)

backend/src/main/resources/db/migration/V144__Migrate_entity_icons_to_lucide.sql (2)

326-343: LGTM!

---

5-6: 🗄️ Data Integrity & Integration

This in-place edit won’t fail Flyway validation here
FlywayConfig catches FlywayValidateException, runs repair(), and migrates again, so a checksum change on V144 won’t break startup. If you want to keep migration history immutable, still move the collation fix into a new migration.

			> Likely an incorrect or invalid review comment.

---

Walkthrough

The V144 migration now explicitly sets utf8mb4_general_ci on the temporary icon mapping table and on the join comparisons used for library, shelf, and magic_shelf updates.

Changes

Migration collation fix

Layer / File(s)	Summary
Temporary table collation declaration backend/src/main/resources/db/migration/V144__Migrate_entity_icons_to_lucide.sql	The prime_to_lucide_icon_map table creation now explicitly declares CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci.
Join condition collation fixes backend/src/main/resources/db/migration/V144__Migrate_entity_icons_to_lucide.sql	The LEFT JOIN ON conditions for library, shelf, and magic_shelf updates now apply COLLATE utf8mb4_general_ci to the prime_icon comparison, with SET and WHERE clauses unchanged.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested labels: backend, enhancement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commit format and clearly describes the migration collation fix.
Description check	✅ Passed	All required sections are present and the description explains the fix, issue link, changes, and verification steps.
Linked Issues check	✅ Passed	The migration changes address the MariaDB collation mismatch described in #1943 by forcing utf8mb4_general_ci where needed.
Out of Scope Changes check	✅ Passed	The changes stay focused on the V144 migration collation fix and do not introduce unrelated code.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

Warning

Review ran into problems

🔥 Problems

Linked repositories: Your configuration references 1 linked repositories, but your current plan allows 0. Analyzed ``, skipped grimmory-tools/grimmory-docs.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}