🔄 Schema Migrations

Evolving the Knowledge Graph schema safely.

Migration Strategy

Versioning

Change Type Version Bump Migration Needed
Add property Minor No (additive)
Add class Minor No (additive)
Rename property Major Yes
Remove property Major Yes
Change type Major Yes

Migration Workflow

1. Plan Migration

1
2
3
4
5
6
7
8

# Generate migration plan
sea schema diff --from v1.0.0 --to v2.0.0

# Output
Breaking changes detected:
  - Renamed: sea:inDomain → sea:inContext
  - Removed: sea:legacyId
  - Changed type: sea:quantity (string → decimal)

2. Create Migration Script

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# migration_v1_to_v2.sparql

# Step 1: Rename property
DELETE { ?s sea:inDomain ?o }
INSERT { ?s sea:inContext ?o }
WHERE { ?s sea:inDomain ?o };

# Step 2: Remove deprecated property
DELETE { ?s sea:legacyId ?o }
WHERE { ?s sea:legacyId ?o };

# Step 3: Convert quantity type
DELETE { ?s sea:quantity ?old }
INSERT { ?s sea:quantity ?new }
WHERE {
  ?s sea:quantity ?old .
  BIND(xsd:decimal(?old) AS ?new)
};

3. Test Migration

1
2
3
4
5
6
7
8

# Create test snapshot
sea graph snapshot --tag "pre-migration-test"

# Apply migration
sea graph migrate --script migration_v1_to_v2.sparql --dry-run

# Validate result
sea graph validate --shapes shapes/v2/

4. Apply Migration

1
2
3
4
5
6
7
8
9
10
11

# Create backup
sea graph snapshot --tag "pre-migration-backup"

# Apply migration
sea graph migrate --script migration_v1_to_v2.sparql

# Verify
sea graph validate --shapes shapes/v2/

# Create post-migration snapshot
sea graph snapshot --version "2.0.0" --tag "post-migration"

Rollback Procedure

1
2
3
4
5
6
7
8

# List available snapshots
sea graph snapshots --tag "pre-migration"

# Restore from backup
sea graph restore --snapshot ifl:snap:pre-migration-backup...

# Verify rollback
sea graph validate --shapes shapes/v1/

Blue-Green Migration

For zero-downtime migrations:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 1. Create parallel graph
sea graph create --name "production-v2"

# 2. Copy and migrate data
sea graph copy --from production --to production-v2
sea graph migrate --target production-v2 --script migration.sparql

# 3. Validate new graph
sea graph validate --target production-v2 --shapes shapes/v2/

# 4. Switch traffic
sea graph activate --name production-v2

# 5. Clean up old graph (after verification period)
sea graph archive --name production-v1

CI/CD Integration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# .github/workflows/schema-migration.yml
jobs:
  migrate:
    steps:
      - name: Validate current schema
        run: sea graph validate --shapes shapes/

      - name: Check for breaking changes
        run: sea schema diff --from ${{ github.base_ref }} --to ${{ github.head_ref }}

      - name: Run migration (staging)
        run: sea graph migrate --target staging --script migrations/

      - name: Validate post-migration
        run: sea graph validate --target staging --shapes shapes/new/