Skip to content

Add a guideline for database schema and index changes - #6140

Merged
danielmarbach merged 1 commit into
masterfrom
database-schema-and-index-changes-guideline
Nov 16, 2026
Merged

danielmarbach merged 1 commit into
masterfrom
database-schema-and-index-changes-guideline

Conversation

@mauroservienti

Copy link
Copy Markdown
Member

Moves the guideline proposed in Particular/Platform#1662 by @ramonsmits into the public engineering context of ServiceControl, as suggested in the review of that pull request. The guideline applies only to ServiceControl, and the engineering context template places repository guidelines under docs/guidelines/, listed in the Guidelines section of docs/README.md.

Changes

  • docs/guidelines/database-schema-and-index-changes.md: the guideline. An index or schema change is a breaking change; ship it in a major release, or opt-in in a minor; record it in the upgrade guide in the same pull request; keep the approval tests current; and a pull request checklist.
  • docs/README.md: a new Guidelines section that lists it, following the engineering context template.
  • docs/testing.md: the IndexDefinitionApprovals paragraph links the guideline.

Differences from Particular/Platform#1662

  • Links to private records (the search engine addendum, the Platform principles and breaking-changes guideline, the customer issue) are replaced by the public ADR and testing docs, or by a one-sentence statement of the rule. The background keeps the public facts of the 6.20.0 change and drops the customer details.
  • The review suggestions on Particular/Platform#1662 are applied: the title, the purpose wording, the locked index behavior from 6.22.2, and the opt-in rule.
  • Relational migrations run during setup (--setup), which installing and upgrading run, not at every start-up. A normal start fails when migrations are pending (Add startup checks to application hosts to fail early on body storage and database migrations #6061). The guideline says so.
  • Rule 5 names SlowMigrationOperationApprovals for SQL Server and PostgreSQL next to IndexDefinitionApprovals, instead of the migration and model snapshot alone.
  • It lists the paths it applies to, as the template asks.

Particular/Platform#1662 can then keep only its definition of done item, pointing here.

Moves the guideline proposed in Particular/Platform#1662 into the
public engineering context of the repository it applies to, as
suggested in its review. It is adapted for a public repository: links
to private records are replaced by the public ADR and testing docs, the
customer reference is removed, and the relational migration section
reflects that migrations run during setup and a normal start fails when
migrations are pending. Rule 5 also names the SlowMigrationOperationApprovals
test for the relational persisters.
@danielmarbach
danielmarbach merged commit 89e3317 into master Nov 16, 2026
36 checks passed
@danielmarbach
danielmarbach deleted the database-schema-and-index-changes-guideline branch November 16, 2026 16:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants