Skip to content

Document database changelog best practices - #55211

Open
IshanKale wants to merge 1 commit into
keycloak:mainfrom
IshanKale:docs/database-changelog-guide
Open

IshanKale wants to merge 1 commit into
keycloak:mainfrom
IshanKale:docs/database-changelog-guide

Conversation

@IshanKale

Copy link
Copy Markdown

Closes #55057

This extends the database schema documentation with guidance for automatic and manual Liquibase migrations, including onSqlOutput, persisted changeset history, deferred indexes, index replacement, custom Java changes, and migration validation.

It also adds a repository skill for creating and reviewing database changelogs using the same practices.

Validation:

  • Skill validation passed
  • git diff --check passed
  • All referenced files and tests were verified
  • No application build required because this only changes documentation and a skill

Explain automatic and manual migration differences, precondition handling, persisted history, deferred indexes, custom changes, and validation. Add an agent skill that applies the same review workflow.

Closes keycloak#55057

Signed-off-by: IshanKale <keshavraokale6@gmail.com>
@IshanKale
IshanKale requested a review from a team as a code owner November 15, 2026 10:19
Copilot AI balanced review requested due to automatic review settings November 15, 2026 10:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for this documentation-only update to Liquibase changelog guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR addresses #55057 by explaining how Keycloak Liquibase changelogs should support both automatic migration and manual SQL generation.

Changes:

  • Documents precondition handling, persisted changeset history, deferred indexes, index replacement, and custom Java changes.
  • Adds guidance on schema parity checks and database migration tests.
  • Introduces a reusable skill for creating and reviewing changelogs using these practices.
File Description
skills/​kc-database-changelog/​SKILL.md Adds a changelog creation and review workflow with validation checks.
docs/​updating-database-schema.md Expands migration guidance with execution-mode differences, reference patterns, and testing pointers.

Review effort: Balanced

@shawkins
shawkins requested review from ahus1 and shawkins November 16, 2026 17:36
@ahus1
ahus1 removed their request for review November 17, 2026 11:02
@ahus1

ahus1 commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

@shawkins - I'm removing myself as a reviewer for now as you have the best knowledge from the previous PR how things should work. I can do a second review after that with my noob eyes to spot items that need additions in the docs. Please re-add me once I should do that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document and add a skill for writing Liquibase changelog entries that work for both automatic and manual migration

3 participants