Database Decomposition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

Phase 1: Initial Sync
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Shared Database (Primary)                                     │
│   ├── users table                                               │
│   ├── orders table                                              │
│   └── products table                                            │
│         │                                                       │
│         │ Initial data copy (bulk migration)                    │
│         ▼                                                       │
│   User Service Database (Shadow)                                │
│   └── users table (copy of users, read-only initially)         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
 
Phase 2: Dual Write
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   User Service                                                  │
│         │                                                       │
│         ├──────────────────────────────────────────────────────┤
│         │                                                       │
│   Write ├───> Shared Database (Primary source of truth)        │
│         │                                                       │
│         └───> User Service DB (Shadow, verified for correctness)│
│                                                                 │
│   Read  ─────> Shared Database (still primary)                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
 
Phase 3: Shadow Read Comparison
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   User Service                                                  │
│         │                                                       │
│   Read  ├───> Shared Database (returns response to user)        │
│         │                                                       │
│         └───> User Service DB (compared, discrepancies logged) │
│                                                                 │
│   Comparison engine logs any differences                        │
│   Team investigates and resolves before cutover                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
 
Phase 4: Traffic Shift
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   User Service                                                  │
│         │                                                       │
│   Read  ├─[10%]─> User Service DB (new primary)                │
│         │                                                       │
│         └─[90%]─> Shared Database                               │
│                                                                 │
│   Write ───> Both databases (dual write continues)             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
 
Phase 5: Complete Cutover
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   User Service                                                  │
│         │                                                       │
│   Read  ─────> User Service DB (100%)                           │
│   Write ─────> User Service DB (new source of truth)           │
│                                                                 │
│   Shared Database (read-only backup, pending decommission)     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

class UserRepository {
  constructor(
    private legacyDb: LegacyDatabase,
    private newDb: NewDatabase,
    private migrationConfig: MigrationConfig,
  ) {}
 
  async createUser(userData: CreateUserData): Promise<User> {
    // Always write to legacy (source of truth during migration)
    const user = await this.legacyDb.users.create(userData);
    
    // Also write to new database (shadow)
    try {
      await this.newDb.users.create({
        id: user.id,  // Use same ID for correlation
        ...userData,
      });
    } catch (error) {
      // Log but don't fail - shadow write failure is not critical
      this.metrics.increment('migration.shadow_write_failure');
      this.logger.error('Shadow write failed', { error, userId: user.id });
    }
    
    return user;
  }
 
  async getUser(userId: string): Promise<User | null> {
    // Read from legacy (source of truth)
    const legacyUser = await this.legacyDb.users.findById(userId);
    
    // Optionally compare with new database
    if (this.migrationConfig.enableReadComparison) {
      this.compareInBackground(userId, legacyUser);
    }
    
    // Optionally read from new database based on traffic percentage
    if (this.shouldReadFromNew()) {
      return this.newDb.users.findById(userId);
    }
    
    return legacyUser;
  }
 
  private async compareInBackground(userId: string, legacyUser: User | null) {
    // Non-blocking comparison
    setImmediate(async () => {
      try {
        const newUser = await this.newDb.users.findById(userId);
        const discrepancies = this.findDiscrepancies(legacyUser, newUser);
        
        if (discrepancies.length > 0) {
          this.metrics.increment('migration.read_discrepancy');
          this.logger.warn('Data discrepancy detected', {
            userId,
            discrepancies,
          });
        }
      } catch (error) {
        this.logger.error('Comparison failed', { error, userId });
      }
    });
  }
 
  private shouldReadFromNew(): boolean {
    // Gradual traffic shift based on configuration
    const percentage = this.migrationConfig.newDbReadPercentage;
    return Math.random() * 100 < percentage;
  }
}

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

# PostgreSQL: pg_dump and pg_restore
pg_dump -h legacy-db -d monolith -t users -t user_profiles \
  | psql -h user-service-db -d userservice
 
# MySQL: mysqldump
mysqldump -h legacy-db monolith users user_profiles \
  | mysql -h user-service-db userservice
 
# AWS DMS for cloud migrations
aws dms create-replication-task \
  --replication-task-identifier user-migration \
  --source-endpoint-arn arn:aws:dms:...:endpoint:source \
  --target-endpoint-arn arn:aws:dms:...:endpoint:target \
  --migration-type full-load-and-cdc \
  --table-mappings file://user-table-mappings.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

class UserMigrationPipeline {
  async runInitialMigration() {
    const batchSize = 10000;
    let offset = 0;
    let hasMore = true;
 
    while (hasMore) {
      // Extract: Fetch batch from legacy database
      const legacyUsers = await this.legacyDb.query(`
        SELECT id, email, first_name, last_name, phone, 
               street_address, city, state, zip, country,
               created_at, updated_at
        FROM users
        ORDER BY id
        LIMIT $1 OFFSET $2
      `, [batchSize, offset]);
 
      if (legacyUsers.length === 0) {
        hasMore = false;
        continue;
      }
 
      // Transform: Convert to new schema
      const transformedUsers = legacyUsers.map(legacy => ({
        id: legacy.id,
        email: legacy.email.toLowerCase(),  // Normalize email
        name: {
          first: legacy.first_name,
          last: legacy.last_name,
        },
        contact: {
          phone: this.normalizePhone(legacy.phone),
        },
        address: {
          street: legacy.street_address,
          city: legacy.city,
          state: legacy.state,
          postalCode: legacy.zip,
          country: this.normalizeCountry(legacy.country),
        },
        metadata: {
          migratedAt: new Date(),
          legacyId: legacy.id,
        },
        createdAt: legacy.created_at,
        updatedAt: legacy.updated_at,
      }));
 
      // Load: Insert into new database
      await this.newDb.users.bulkInsert(transformedUsers);
 
      // Progress tracking
      offset += batchSize;
      this.logger.info(`Migrated ${offset} users`);
      
      // Throttle to avoid overwhelming databases
      await this.sleep(100);
    }
 
    this.logger.info('Initial migration complete');
  }
 
  private normalizePhone(phone: string): string {
    // Remove non-numeric characters, format consistently
    return phone?.replace(/\D/g, '') || null;
  }
 
  private normalizeCountry(country: string): string {
    // Convert to ISO country code
    return countryCodeMapping[country?.toLowerCase()] || country;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Timeline of CDC Migration:
 
T=0: Start CDC capture on legacy database
     All changes are captured and queued
 
T=0 to T+8h: Run initial bulk copy
     - Legacy: 10 million records copied
     - CDC queue: 50,000 changes accumulated
 
T+8h: Apply accumulated CDC changes
     - Process 50,000 queued changes
     - Takes 10 minutes
 
T+8h 10m: Steady state
     - Bulk copy done
     - CDC queue drained
     - Real-time sync begins
 
CDC Workflow:
┌────────────────────────────────────────────────────────────────┐
│                                                                │
│  Legacy DB ──[Change Log/WAL]──> CDC Connector                │
│                                       │                        │
│                                       ▼                        │
│                              Kafka / Event Queue               │
│                                       │                        │
│                                       ▼                        │
│  New DB <────────────────────── CDC Consumer                  │
│                               applies changes                  │
│                                                                │
└────────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

async createUser(userData: CreateUserData): Promise<User> {
  // Step 1: Write to legacy (synchronous, must succeed)
  const user = await this.legacyDb.users.create(userData);
  
  // Step 2: Replicate to new (async, failure tolerated)
  this.replicateToNew(user).catch(err => {
    this.logger.error('Replication failed', { err, userId: user.id });
    this.queueForRetry(user);  // Will retry later
  });
  
  return user;
}
 
// Periodic job catches up any missed replications
async reconcileDatabases() {
  const legacyUsers = await this.legacyDb.users.findModifiedSince(
    this.lastReconcileTime
  );
  
  for (const user of legacyUsers) {
    await this.replicateToNew(user);
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

async createUser(userData: CreateUserData): Promise<User> {
  // Single transaction ensures atomicity
  return this.legacyDb.transaction(async (tx) => {
    // Create the user
    const user = await tx.users.create(userData);
    
    // Record the change in outbox table (same transaction)
    await tx.outbox.create({
      aggregateType: 'User',
      aggregateId: user.id,
      eventType: 'UserCreated',
      payload: JSON.stringify(user),
      status: 'pending',
      createdAt: new Date(),
    });
    
    return user;
  });
}
 
// Separate process polls outbox and applies to new database
class OutboxProcessor {
  async process() {
    const pendingEvents = await this.legacyDb.outbox.findByStatus('pending');
    
    for (const event of pendingEvents) {
      try {
        await this.applyToNewDatabase(event);
        await this.legacyDb.outbox.updateStatus(event.id, 'processed');
      } catch (error) {
        await this.legacyDb.outbox.updateStatus(event.id, 'failed');
        this.logger.error('Outbox processing failed', { event, error });
      }
    }
  }
}

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

class UserRepository {
  constructor(private config: MigrationConfig) {}
 
  async createUser(userData: CreateUserData): Promise<User> {
    if (this.config.newDatabaseIsPrimary) {
      // New database is source of truth
      const user = await this.newDb.users.create(userData);
      
      // Backfill to legacy for rollback safety
      this.backfillToLegacy(user).catch(err => {
        this.logger.warn('Legacy backfill failed', { err, userId: user.id });
        // Not critical - legacy is no longer primary
      });
      
      return user;
    } else {
      // Legacy is still primary (previous code path)
      return this.legacyPrimaryCreate(userData);
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

class UserRepository {
  async getUser(userId: string): Promise<User | null> {
    const config = await this.featureFlags.get('user_db_migration');
    
    // Route based on percentage
    if (this.shouldUseNewDatabase(config.readPercentage)) {
      try {
        return await this.newDb.users.findById(userId);
      } catch (error) {
        // Fallback to legacy on error
        this.metrics.increment('migration.new_db_fallback');
        return this.legacyDb.users.findById(userId);
      }
    }
    
    return this.legacyDb.users.findById(userId);
  }
 
  private shouldUseNewDatabase(percentage: number): boolean {
    // Deterministic routing based on request ID for consistency
    const requestHash = hash(this.requestContext.requestId);
    return (requestHash % 100) < percentage;
  }
}
 
// Progressive rollout schedule
// Day 1: 1% read traffic to new DB, monitor closely
// Day 2: 5% read traffic if Day 1 successful
// Day 3: 10% read traffic
// Day 5: 25% read traffic
// Day 7: 50% read traffic
// Day 10: 100% read traffic
// Day 14: Switch write traffic to new DB as primary

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

class UserRepository {
  async getUser(userId: string): Promise<User | null> {
    const user = await this.getRoutingInfo(userId);
    
    // Internal users first
    if (user.isInternalUser) {
      return this.newDb.users.findById(userId);
    }
    
    // Then beta users who opted in
    if (user.isBetaTester) {
      return this.newDb.users.findById(userId);
    }
    
    // Then users by region (easier to support during business hours)
    if (this.isMigratedRegion(user.region)) {
      return this.newDb.users.findById(userId);
    }
    
    // Everyone else stays on legacy until their segment is migrated
    return this.legacyDb.users.findById(userId);
  }
 
  private async isMigratedRegion(region: string): Promise<boolean> {
    const migratedRegions = ['US-WEST', 'EU-WEST'];  // Gradually expand
    return migratedRegions.includes(region);
  }
}

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

class DatabaseRouter {
  async route(userId: string): Promise<Database> {
    // Use consistent hashing for deterministic routing
    const bucket = consistentHash(userId) % 100;
    const cutoverBucket = await this.featureFlags.get('migration_cutover_bucket');
    
    if (bucket < cutoverBucket) {
      return this.newDb;
    }
    return this.legacyDb;
  }
}
 
// The same user always routes to the same database
// Moving cutoverBucket from 0 to 100 gradually migrates all users
// User with bucket=25 moves when cutoverBucket reaches 26
// Prevents user from flip-flopping between databases

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

// Emergency rollback - takes effect immediately
await featureFlags.set('user_db_migration', {
  readPercentage: 0,      // All reads go to legacy
  writeToNew: false,      // Stop writing to new DB
  newIsPrimary: false,    // Ensure legacy is source of truth
});
 
// Or via CLI/API call
$ curl -X POST https://api.featureflags.io/flags/user_db_migration/disable
 
// Alert team
await alerting.critical('Database migration rolled back', {
  reason: 'Error rate exceeded threshold',
  rollbackTime: new Date(),
  trafficPercentage: previousPercentage,
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// If new DB has incorrect data, re-sync from legacy
class MigrationRollback {
  async resyncFromLegacy(startTime: Date, endTime: Date) {
    // Find all records modified during the problematic period
    const affectedRecords = await this.legacyDb.users.findModifiedBetween(
      startTime,
      endTime
    );
    
    this.logger.warn(`Rolling back ${affectedRecords.length} records`);
    
    for (const legacyRecord of affectedRecords) {
      // Overwrite new DB with legacy data
      await this.newDb.users.upsert(
        this.transformForNewSchema(legacyRecord)
      );
      
      // Log for audit
      await this.auditLog.record({
        action: 'migration_rollback',
        recordId: legacyRecord.id,
        reason: 'data_correction',
        rolledBackAt: new Date(),
      });
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Post-Cutover Rollback Procedure:
 
1. STOP: Halt all writes (brief downtime may be necessary)
 
2. SYNC: Apply all changes from new DB back to legacy
   - Query new DB for all records modified since cutover
   - Transform to legacy schema
   - Apply to legacy DB
   
3. VERIFY: Ensure legacy has all data
   - Run reconciliation queries
   - Compare record counts
   - Validate critical business data
 
4. SWITCH: Redirect traffic to legacy
   - Update feature flags
   - Verify traffic is flowing to legacy
   - Monitor closely
 
5. RESUME: Allow writes
   - Legacy is now primary again
   - New DB becomes shadow (or is paused)
 
Timeline: 15-60 minutes depending on data volume and verification needs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

class DataComparator {
  async compareRead(userId: string): Promise<void> {
    const [legacyResult, newResult] = await Promise.all([
      this.legacyDb.users.findById(userId),
      this.newDb.users.findById(userId),
    ]);
 
    const comparison = this.compare(legacyResult, newResult);
    
    if (!comparison.isEqual) {
      this.metrics.increment('migration.comparison.mismatch');
      
      await this.discrepancyLog.record({
        entity: 'User',
        entityId: userId,
        differences: comparison.differences,
        legacyValue: this.redact(legacyResult),
        newValue: this.redact(newResult),
        timestamp: new Date(),
      });
      
      // Alert if mismatch rate exceeds threshold
      if (await this.mismatchRateExceedsThreshold()) {
        await this.alertMigrationTeam('Mismatch rate too high');
      }
    } else {
      this.metrics.increment('migration.comparison.match');
    }
  }
 
  private compare(legacy: any, newRecord: any): ComparisonResult {
    const differences: Difference[] = [];
    
    // Compare each field, accounting for schema transformations
    for (const field of this.comparisonFields) {
      const legacyValue = this.extractField(legacy, field.legacyPath);
      const newValue = this.extractField(newRecord, field.newPath);
      
      if (!field.comparator(legacyValue, newValue)) {
        differences.push({
          field: field.name,
          legacyValue,
          newValue,
        });
      }
    }
    
    return {
      isEqual: differences.length === 0,
      differences,
    };
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

class ReconciliationJob {
  async runFullReconciliation(): Promise<ReconciliationReport> {
    const report: ReconciliationReport = {
      startTime: new Date(),
      totalLegacyRecords: 0,
      totalNewRecords: 0,
      missingInNew: [],
      missingInLegacy: [],
      mismatches: [],
    };
 
    // Get all IDs from both databases
    const legacyIds = new Set(await this.legacyDb.users.getAllIds());
    const newIds = new Set(await this.newDb.users.getAllIds());
 
    report.totalLegacyRecords = legacyIds.size;
    report.totalNewRecords = newIds.size;
 
    // Find records missing in new database
    for (const id of legacyIds) {
      if (!newIds.has(id)) {
        report.missingInNew.push(id);
      }
    }
 
    // Find records in new but not in legacy (shouldn't happen normally)
    for (const id of newIds) {
      if (!legacyIds.has(id)) {
        report.missingInLegacy.push(id);
      }
    }
 
    // Compare content of matching records (sample for large datasets)
    const sampleIds = this.sample(Array.from(legacyIds), 10000);
    for (const id of sampleIds) {
      const [legacy, newRecord] = await Promise.all([
        this.legacyDb.users.findById(id),
        this.newDb.users.findById(id),
      ]);
      
      if (!this.recordsMatch(legacy, newRecord)) {
        report.mismatches.push({
          id,
          differences: this.findDifferences(legacy, newRecord),
        });
      }
    }
 
    report.endTime = new Date();
    return report;
  }
}

1
2
3
4
5
6
7
8
9
10

-- Current state: Foreign keys across domains
CREATE TABLE orders (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id),  -- Will be in different DB
  product_id UUID NOT NULL REFERENCES products(id),  -- Will be in different DB
  created_at TIMESTAMP
);
 
-- Problem: When orders moves to its own database,
-- these foreign keys cannot exist across databases

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

class OrderService {
  async createOrder(orderData: CreateOrderInput): Promise<Order> {
    // Validate references exist before proceeding
    await this.validateReferences(orderData);
    
    // Store only the ID reference, not a foreign key
    const order = await this.orderDb.orders.create({
      id: generateId(),
      userId: orderData.userId,      // Just an ID, no FK constraint
      productIds: orderData.items.map(i => i.productId),  // Just IDs
      ...orderData,
    });
    
    return order;
  }
 
  private async validateReferences(orderData: CreateOrderInput): Promise<void> {
    // Check user exists via User Service API
    const user = await this.userServiceClient.getUser(orderData.userId);
    if (!user) {
      throw new ValidationError(`User ${orderData.userId} not found`);
    }
    if (!user.canPlaceOrders) {
      throw new ValidationError(`User ${orderData.userId} cannot place orders`);
    }
 
    // Check products exist via Product Service API
    const productIds = orderData.items.map(i => i.productId);
    const products = await this.productServiceClient.getProducts(productIds);
    
    const foundIds = new Set(products.map(p => p.id));
    const missingIds = productIds.filter(id => !foundIds.has(id));
    
    if (missingIds.length > 0) {
      throw new ValidationError(`Products not found: ${missingIds.join(', ')}`);
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Dependency graph:
orders -> users (orders.user_id references users.id)
orders -> products (orders.product_id references products.id)
 
Migration sequence:
 
Step 1: Add application-level validation (while FKs still exist)
        - Order Service validates via API before creating orders
        - Both validation paths active: app + DB FK
 
Step 2: Drop foreign key constraints
        ALTER TABLE orders DROP CONSTRAINT orders_user_id_fkey;
        ALTER TABLE orders DROP CONSTRAINT orders_product_id_fkey;
        - Application validation is now the only enforcement
        - Test thoroughly
 
Step 3: Migrate tables to separate databases
        - users -> User Service DB
        - products -> Product Service DB
        - orders -> Order Service DB
 
Step 4: Handle orphaned references (cleanup)
        - Find any orders referencing non-existent users
        - Decide: soft-delete, archive, or flag for review

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

┌─────────────────────────────────────────────────────────────────────┐
│                    USER SERVICE MIGRATION DASHBOARD                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  SYNC STATUS                         TRAFFIC ROUTING                │
│  ════════════                        ═══════════════                │
│  Legacy records:     10,234,567      Read traffic:                  │
│  New DB records:     10,234,565      ├── Legacy: 60%                │
│  Sync lag:           2 records       └── New DB: 40%                │
│  Last sync:          2 seconds ago                                  │
│                                      Write traffic:                 │
│                                      └── Both (dual write)          │
│                                                                      │
│  DATA QUALITY                        PERFORMANCE                    │
│  ════════════                        ═══════════                    │
│  Comparison checks:  1,234,567       Legacy p99: 45ms               │
│  Matches:            1,234,550       New DB p99: 38ms               │
│  Mismatches:         17 (0.001%)     Error rate: 0.01%              │
│  Last mismatch:      12 min ago                                     │
│                                                                      │
│  ROLLBACK STATUS                     MIGRATION PHASE                │
│  ═══════════════                     ═══════════════                │
│  Rollback ready:     ✓ Yes          Phase: Traffic Shifting        │
│  Legacy current:     ✓ Yes          Progress: 40% reads to new     │
│  Backfill running:   ✓ Yes          Next milestone: 50% (Day 7)    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

class MigrationRunbook {
  async increaseTrafficToNewDatabase(targetPercentage: number) {
    // Pre-flight checks
    await this.validatePreConditions([
      'sync_lag_under_threshold',
      'mismatch_rate_acceptable', 
      'new_db_latency_acceptable',
      'error_rate_acceptable',
    ]);
 
    // Record current state for rollback
    const previousPercentage = await this.getCurrentPercentage();
    await this.recordCheckpoint(previousPercentage);
 
    // Gradual increase (not instant jump)
    const steps = this.calculateSteps(previousPercentage, targetPercentage);
    
    for (const step of steps) {
      await this.setTrafficPercentage(step.percentage);
      await this.wait(step.observationPeriodMs);
      
      const health = await this.checkSystemHealth();
      if (!health.isHealthy) {
        await this.rollbackToPercentage(previousPercentage);
        throw new MigrationError(`Health check failed at ${step.percentage}%`);
      }
    }
 
    await this.notifyTeam(`Traffic increased to ${targetPercentage}%`);
  }
}