git.stella-ops.org/docs/implplan/MIGRATION_CONSOLIDATION_20251229.md

Migration Consolidation - Pre-v1.0 Baseline

Date: 2025-12-29 Reason: Pre-v1.0 release - consolidate incremental migrations into single baseline per repository

---

Summary

PostgreSQL migrations for SbomService.Lineage created during recent sprint work have been consolidated into a single baseline 00001_InitialSchema.sql file. This follows best practices for pre-v1.0 development where the schema is still evolving and a clean baseline is preferred over numerous incremental migrations.

VexLens.Persistence already had a single baseline migration from a previous sprint, so no consolidation was required.

---

Consolidated Migrations

1. SbomService.Lineage

Consolidated File: src/SbomService/__Libraries/StellaOps.SbomService.Lineage/Persistence/Migrations/00001_InitialSchema.sql

Original Migrations (deleted):

• 20251229_001_CreateLineageTables.sql
• 20251229_002_CreateVexDeltasTable.sql
• 20251229_003_CreateSbomVerdictLinksTable.sql

Tables Created:

1. sbom.sbom_lineage_edges - SBOM artifact relationships (parent/build/base)

   • 4 indexes for graph traversal
   • RLS policy for tenant isolation

2. vex.vex_deltas - VEX status transitions between SBOM versions

   • 5 indexes for delta queries
   • RLS policy for tenant isolation
   • Supports replay_hash for determinism

3. sbom.sbom_verdict_links - Links SBOM versions to VEX consensus

   • 5 indexes for efficient joins
   • RLS policy for tenant isolation

Line Count: 120 lines (consolidated from 114 total lines across 3 files)

---

2. VexLens.Persistence

Status: Already has baseline migration - no consolidation needed

Existing File: src/VexLens/StellaOps.VexLens.Persistence/Migrations/001_consensus_projections.sql

Note: VexLens.Persistence already had a single baseline migration in place from a previous sprint (SPRINT_20251228_007_BE). No consolidation was required.

---

Migration Naming Convention

Pre-v1.0 Format: 00001_InitialSchema.sql

• 00001: Sequential migration number (future migrations will be 00002, 00003, etc.)
• InitialSchema: Descriptive name indicating this is the baseline schema
• After v1.0 release, migrations will use timestamp-based naming: YYYYMMDD_HHmmss_Description.sql

---

Repository Pattern

Each repository module has its own Migrations/ directory:

src/
├── SbomService/
│   └── __Libraries/
│       └── StellaOps.SbomService.Lineage/
│           └── Persistence/
│               └── Migrations/
│                   └── 00001_InitialSchema.sql
│
└── VexLens/
    └── __Libraries/
        └── StellaOps.VexLens.Persistence/
            └── Migrations/
                └── 00001_InitialSchema.sql

---

Schema Organization

All tables use schema prefixes:

• sbom.* - SBOM-related tables (lineage, versions, verdict links)
• vex.* - VEX-related tables (deltas, consensus projections)

This follows the StellaOps multi-schema pattern for logical separation and RLS policy isolation.

---

Row-Level Security (RLS)

All tables include:

1. tenant_id column (UUID NOT NULL)
2. RLS enabled on table
3. Policy using current_setting('app.current_tenant_id', true)::UUID

Example:

ALTER TABLE sbom.sbom_lineage_edges ENABLE ROW LEVEL SECURITY;

CREATE POLICY IF NOT EXISTS lineage_edges_tenant_isolation
ON sbom.sbom_lineage_edges
    FOR ALL
    USING (tenant_id = current_setting('app.current_tenant_id', true)::UUID);

---

Index Strategy

Each table follows consistent index patterns:

1. Primary queries: Covering main query paths (e.g., by digest, by CVE)
2. Tenant isolation: All indexes include tenant_id
3. Temporal queries: DESC ordering on created_at/computed_at
4. Partial indexes: WHERE clauses for filtered queries (e.g., status changes only)

Example:

CREATE INDEX IF NOT EXISTS idx_vex_deltas_status_change
ON vex.vex_deltas(tenant_id, from_status, to_status)
WHERE from_status != to_status;

---

Verification

# Verify SbomService.Lineage baseline migration exists
find src/SbomService -name "00001_InitialSchema.sql"

# Output:
# src/SbomService/__Libraries/StellaOps.SbomService.Lineage/Persistence/Migrations/00001_InitialSchema.sql

# Verify no dated migrations remain in SbomService.Lineage
find src/SbomService -name "20251229*.sql"

# Output: (empty - all removed)

# VexLens uses existing baseline from previous sprint
ls src/VexLens/StellaOps.VexLens.Persistence/Migrations/

# Output:
# 001_consensus_projections.sql

---

Post-v1.0 Migration Strategy

After v1.0 release, migrations will:

1. Use timestamp naming: YYYYMMDD_HHmmss_Description.sql
2. Be applied incrementally (no more consolidation)
3. Include rollback scripts where appropriate
4. Be tracked in a migrations table for version control

---

Related Documentation

• docs/db/SPECIFICATION.md - Database schema specification
• docs/operations/postgresql-guide.md - PostgreSQL operations guide
• docs/implplan/archived/COMPLETION_SUMMARY_20251229.md - Sprint completion summary

---

Consolidation Completed: 2025-12-29 Modules Affected: SbomService.Lineage Files Removed: 3 incremental migrations (20251229_001, _002, _003) Files Created: 1 baseline migration (00001_InitialSchema.sql) Files Unchanged: VexLens.Persistence (already had baseline from previous sprint)