core/docs/STRING_ID_MIGRATION_STATUS.md

String ID Migration - Complete Implementation Status

✅ Completed Work

Phase 1: ID Generation Infrastructure (Complete)

• ✅ ID sequence table created
• ✅ ID generator service with thread-safe generation
• ✅ Comprehensive tests including concurrency

Phase 2: Dual-Write (Complete)

• ✅ Migration 0010 applied - sid columns added to all tables
• ✅ All existing data backfilled with formatted IDs
• ✅ All domain models updated with dual ID fields
• ✅ All repositories updated for dual-write

Phase 3: String IDs Only (In Progress)

✅ Completed

1. Migration Created: /migrations/0011_switch_to_string_ids/up.sql

   • Drops integer id columns
   • Renames sid → id
   • Updates all foreign keys to use string IDs
   • ⚠️ Not yet applied - ready for deployment

2. Domain Models Updated:

   • ✅ /internal/domain/registry.go - All types use string for IDs
   • ✅ /internal/domain/tickets.go - String IDs
   • ✅ /internal/domain/failure_events.go - String IDs

3. Repositories Updated (5 of 9):

   • ✅ /internal/repository/registry/customers.go
   • ✅ /internal/repository/registry/projects.go
   • ✅ /internal/repository/registry/locations.go
   • ✅ /internal/repository/registry/lots.go
   • ⏳ /internal/repository/registry/assets.go - NEEDS UPDATE
   • ⏳ /internal/repository/registry/components.go - NEEDS UPDATE
   • ⏳ /internal/repository/registry/installations.go - NEEDS UPDATE
   • ⏳ /internal/repository/tickets/tickets.go - NEEDS UPDATE
   • ⏳ /internal/repository/failures/failures.go - NEEDS UPDATE

⏳ Remaining Work

Repositories (4 files to update):

1. assets.go - Change Create() signature to accept projectID string, locationID *string, return generated ID directly
2. components.go - Change Create() to accept lotID *string, return generated ID
3. installations.go - Update queries to use string IDs
4. tickets/tickets.go - Update Upsert() and LinkToAsset() to use string IDs
5. failures/failures.go - Update Upsert() to use string IDs

Pattern for remaining repositories:

// Change method signatures from int64 to string
func (r *XRepository) Get(ctx context.Context, id string) (domain.X, error)
func (r *XRepository) Create(ctx context.Context, ...) (domain.X, error)

// In Create, generate ID and use it directly:
id, err := r.idgen.Generate(ctx, idgen.X)
_, err = r.db.ExecContext(ctx, `INSERT INTO table (id, ...) VALUES (?, ...)`, id, ...)
return r.Get(ctx, id)  // No more LastInsertId()

// Update all NULL foreign key handling:
var foreignID *string  // instead of *int64
var nullForeignID sql.NullString  // instead of sql.NullInt64

API Layer (needs review):

• All route handlers that call repository methods
• Path parameter parsing (already strings in most cases)
• Any business logic that works with IDs

Other Files (may need updates):

• Ingest service - hardware/software parsing
• Timeline events - if they reference IDs
• Any test files

Next Steps

Option 1: Complete Remaining Repositories (Recommended)

Continue updating the remaining 4 repository files following the established pattern, then apply migration.

Option 2: Test Current State

1. Try to compile with current changes
2. Identify all compilation errors
3. Fix systematically

Option 3: Apply Migration and Iterate

1. Apply migration 0011
2. Try to run application
3. Fix errors as they appear

Migration Command (When Ready)

# Backup database first!
docker exec reanimator-mariadb mariadb-dump -u reanimator -preanimator reanimator > backup_before_string_ids.sql

# Apply migration
docker exec -i reanimator-mariadb mariadb -u reanimator -preanimator reanimator < migrations/0011_switch_to_string_ids/up.sql

# Verify
docker exec -i reanimator-mariadb mariadb -u reanimator -preanimator reanimator -e "DESCRIBE customers"

Rollback Strategy

⚠️ WARNING: Migration 0011 is NOT easily reversible. The auto-increment integer IDs will be lost.

Rollback options:

1. Restore from database backup (recommended)
2. Manually reconstruct schema (complex, data-dependent)

Testing After Migration

# Compile
go build ./...

# Run tests
go test ./...

# Manual verification
go run verify_string_ids.go

Benefits of String IDs

• ✅ Human-readable IDs (CR-0000001 instead of 1)
• ✅ Self-documenting entity types
• ✅ Better for support and debugging
• ✅ Copy-paste friendly in logs and UIs
• ✅ Future-proof for distributed systems
• ✅ No integer overflow concerns