Comprehensive migration planning

When changing identifier systems (e.g., from using `getInternalId()` to `getSequence()`), implement comprehensive migration strategies to preserve data integrity and backward compatibility. For each change:

copy reviewer prompt

Prompt

Reviewer Prompt
Deploy Agent

When changing identifier systems (e.g., from using getInternalId() to getSequence()), implement comprehensive migration strategies to preserve data integrity and backward compatibility. For each change:

  1. Create explicit migration scripts to update or rename existing resources
  2. Implement fallback mechanisms for transitional periods
  3. Update all related queries, metrics, and references consistently
  4. Test thoroughly with real data before deploying
// Example migration for collection renaming:
public function migrateCollections(): void
{
    $buckets = $this->dbForProject->find('buckets');
    
    foreach ($buckets as $bucket) {
        $oldName = 'bucket_' . $bucket->getInternalId();
        $newName = 'bucket_' . $bucket->getSequence();
        
        if ($this->dbForProject->hasCollection($oldName) && !$this->dbForProject->hasCollection($newName)) {
            // Rename collection to preserve existing data
            $this->dbForProject->renameCollection($oldName, $newName);
            Console::success("Migrated collection {$oldName} → {$newName}");
        }
    }
}

Without proper migration planning, changes to identifier systems often result in orphaned data, broken queries, and critical production issues.

Source discussions