2.2 KiB
2.2 KiB
Schema Deltas
Incremental SQL scripts applied to existing environments after the canonical schema
(../lcbp3-v1.8.0-schema-02-tables.sql) has been updated.
Naming Convention
YYYY-MM-DD-descriptive-name.sql
Examples:
2026-04-22-add-rfa-revision-column.sql2026-04-25-index-correspondence-created-at.sql2026-05-01-add-workflow-step-attachment-table.sql
Rules (per ADR-009)
- Never replace the canonical
lcbp3-v1.8.x-schema-02-tables.sql— update it first, then add the delta here. - Idempotent where possible — prefer
CREATE TABLE IF NOT EXISTS,ALTER TABLE … ADD COLUMN IF NOT EXISTS, etc. - No TypeORM migrations — these
.sqlfiles are the only schema deployment mechanism. - Data backfill goes through n8n workflows, not this directory.
- Update Data Dictionary (
../03-01-data-dictionary.md) in the same PR that adds a delta.
Delta Template
-- Delta: <short description>
-- Date: YYYY-MM-DD
-- Related ADR: ADR-XXX (if applicable)
-- Related Spec: specs/NN-NAME/spec.md (if applicable)
-- Applied in: v1.8.X → v1.8.Y
-- ------------------------------------------------------------
-- Schema changes
-- ------------------------------------------------------------
ALTER TABLE <table>
ADD COLUMN <col> <type> <constraints>;
-- ------------------------------------------------------------
-- Indexes (if needed)
-- ------------------------------------------------------------
CREATE INDEX idx_<table>_<col> ON <table>(<col>);
-- ------------------------------------------------------------
-- Verification query (optional)
-- ------------------------------------------------------------
-- SELECT COUNT(*) FROM <table> WHERE <col> IS NOT NULL;
Rollback
Every delta should have a reversible companion (YYYY-MM-DD-descriptive-name.rollback.sql)
where physically possible. Dropping NOT NULL columns with existing data is explicitly
irreversible — document in the delta header when rollback is impossible.