Overview

Tenant DB Migration provides guidance for performing tenant-aware migrations in legacy systems. It documents the three legacy steps and notes that this approach is deprecated in favor of a newer migration framework.

How This Skill Works

This legacy approach begins by backfilling missing tenantId values, then introducing composite indexes to support tenant-scoped queries, and finally validating rollback procedures to ensure safety if the migration fails.

When to Use It

• You’re working with an old multi-tenant schema that lacks a tenantId column.
• You need to prepare for a migration that relies on composite indexes.
• You must verify rollback procedures as part of the migration process.
• You’re auditing or migrating older tenants in an environment not yet switched to the new framework.
• You’re planning a staged migration before adopting a new framework.

Quick Start

1. Step 1: Inventory tables to identify missing tenantId and plan backfill.
2. Step 2: Backfill tenantId values and add required composite indexes.
3. Step 3: Run the migration in staging and verify rollback procedures.

Best Practices

• Ensure tenantId is present or backfilled before adding indexes.
• Backfill in a controlled maintenance window with backups.
• Create composite indexes on (tenantId, ...) to accelerate tenant-scoped queries.
• Test rollback scenarios in staging or a replica environment.
• Document the steps, timing, and rollback plan for auditability.

Example Use Cases

• Backfill tenantId on the customers table where tenantId is NULL.
• Add a composite index on (tenantId, createdAt) to optimize per-tenant reads.
• Simulate a migration failure and verify that rollback restores previous data state.
• Apply the legacy steps to migrate orders and invoices in a tenant-aware system.
• Post-migration audit to ensure tenant scopes are preserved and queries remain correct.

Frequently Asked Questions