From 6e9cee9d34fe67e6cb2cfdcefb1ce2c7b5c0dadb Mon Sep 17 00:00:00 2001 From: Sacha Al Himdani Date: Fri, 20 Mar 2026 10:47:18 +0100 Subject: [PATCH] Document migration rules for indexes and defaults Clarify that indexes should not be added speculatively and should only be introduced when justified by production query latency. Also document that columns should avoid DEFAULT clauses, with guidance on backfilling non-nullable columns. Signed-off-by: Sacha Al Himdani --- contrib/claude/coredata.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/contrib/claude/coredata.md b/contrib/claude/coredata.md index 15cd1e638..fff07e114 100644 --- a/contrib/claude/coredata.md +++ b/contrib/claude/coredata.md @@ -158,7 +158,11 @@ Each entity gets a unique `uint16` constant in `entity_type_reg.go`. **Never reu ## Migrations -Files in `pkg/coredata/migrations/` use timestamp naming: `YYYYMMDDTHHMMSSZ.sql` (UTC). One logical change per file. Always create indexes for frequently queried columns. +Files in `pkg/coredata/migrations/` use timestamp naming: `YYYYMMDDTHHMMSSZ.sql` (UTC). One logical change per file. + +**No indexes by default.** Only add indexes when justified by observed query latency in production environments. Do not speculatively create indexes on new tables or columns. This rule does not apply to indexes that enforce constraints, such as unique indexes. + +**Avoid default values.** Columns should not have `DEFAULT` clauses. When adding a non-nullable column to an existing table, use a `DEFAULT` to backfill existing rows, then drop it in the same migration. ## New entity checklist