66 lines
2.2 KiB
Markdown
66 lines
2.2 KiB
Markdown
# 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.sql`
|
|
- `2026-04-25-index-correspondence-created-at.sql`
|
|
- `2026-05-01-add-workflow-step-attachment-table.sql`
|
|
|
|
## Rules (per ADR-009)
|
|
|
|
1. **Never replace** the canonical `lcbp3-v1.8.x-schema-02-tables.sql` — update it first, then add the delta here.
|
|
2. **Idempotent where possible** — prefer `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE … ADD COLUMN IF NOT EXISTS`, etc.
|
|
3. **No TypeORM migrations** — these `.sql` files are the only schema deployment mechanism.
|
|
4. **Data backfill** goes through **n8n workflows**, not this directory.
|
|
5. **Update Data Dictionary** (`../03-01-data-dictionary.md`) in the same PR that adds a delta.
|
|
|
|
## Delta Template
|
|
|
|
```sql
|
|
-- 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.
|
|
|
|
## References
|
|
|
|
- [ADR-009 Database Migration Strategy](../../06-Decision-Records/ADR-009-database-migration-strategy.md)
|
|
- [Canonical Schema](../lcbp3-v1.8.0-schema-02-tables.sql)
|
|
- [Data Dictionary](../03-01-data-dictionary.md)
|