database-migration

数据库迁移

在生产环境中演进数据库架构的安全模式。

迁移原则

1. 向后兼容 - 新代码可与旧架构配合使用
2. 可回滚 - 必要时可以回滚
3. 经过测试 - 上线前在预发布环境中验证
4. 渐进式 - 小步变更，而非一次性大规模变更
5. 零停机 - 服务不中断

安全迁移模式

阶段 1：添加新内容（兼容）

-- Add new column (nullable initially)
ALTER TABLE users ADD COLUMN full_name VARCHAR(255) NULL;

-- Deploy new code that writes to both old and new
UPDATE users SET full_name = CONCAT(first_name, ' ', last_name);

阶段 2：迁移数据

-- Backfill existing data
UPDATE users
SET full_name = CONCAT(first_name, ' ', last_name)
WHERE full_name IS NULL;

阶段 3：设为必需

-- Make column required
ALTER TABLE users ALTER COLUMN full_name SET NOT NULL;

阶段 4：移除旧内容（部署新代码后）

-- Remove old columns
ALTER TABLE users DROP COLUMN first_name;
ALTER TABLE users DROP COLUMN last_name;

常见迁移

添加索引

-- Create index concurrently (PostgreSQL)
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

重命名列

-- Phase 1: Add new column
ALTER TABLE users ADD COLUMN email_address VARCHAR(255);

-- Phase 2: Copy data
UPDATE users SET email_address = email;

-- Phase 3: Drop old column (after deploy)
ALTER TABLE users DROP COLUMN email;

更改列类型

-- Phase 1: Add new column with new type
ALTER TABLE products ADD COLUMN price_cents INTEGER;

-- Phase 2: Migrate data
UPDATE products SET price_cents = CAST(price * 100 AS INTEGER);

-- Phase 3: Drop old column
ALTER TABLE products DROP COLUMN price;
ALTER TABLE products RENAME COLUMN price_cents TO price;

添加外键

-- Add column first
ALTER TABLE orders ADD COLUMN user_id INTEGER NULL;

-- Populate data
UPDATE orders SET user_id = (
    SELECT id FROM users WHERE users.email = orders.user_email
);

-- Add foreign key
ALTER TABLE orders
ADD CONSTRAINT fk_orders_users
FOREIGN KEY (user_id) REFERENCES users(id);

迁移工具

Python（Alembic）

# Generate migration
alembic revision --autogenerate -m "add user full_name"

# Apply migration
alembic upgrade head

# Rollback
alembic downgrade -1

JavaScript（Knex）

// Create migration
knex migrate:make add_full_name

// Apply migrations
knex migrate:latest

// Rollback
knex migrate:rollback

Rails

# Generate migration
rails generate migration AddFullNameToUsers full_name:string

# Run migrations
rails db:migrate

# Rollback
rails db:rollback

测试迁移

def test_migration_forward_backward():
    # Apply migration
    apply_migration("add_full_name")

    # Verify schema
    assert column_exists("users", "full_name")

    # Rollback
    rollback_migration()

    # Verify rollback
    assert not column_exists("users", "full_name")

危险操作

❌ 避免在生产环境中执行

-- Locks table for long time
ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL;

-- Can't rollback
DROP TABLE old_users;

-- Breaks existing code immediately
ALTER TABLE users DROP COLUMN email;

✅ 安全替代方案

-- Add as nullable first
ALTER TABLE users ADD COLUMN email VARCHAR(255) NULL;

-- Rename instead of drop
ALTER TABLE old_users RENAME TO archived_users;

-- Keep old column until new code deployed
-- (multi-phase approach)

回滚策略

-- Every migration needs DOWN
-- UP
ALTER TABLE users ADD COLUMN full_name VARCHAR(255);

-- DOWN
ALTER TABLE users DROP COLUMN full_name;

决策支持

快速决策指南

要更改架构？

• 破坏性变更（删除／修改数据）→ 多阶段迁移（扩展-收缩）
• 增量变更（新增列／表）→ 单阶段迁移
• 大型表（数百万行）→ 为索引使用 CONCURRENTLY

需要零停机？

• 架构变更 → 扩展-收缩模式（5 个阶段）
• 数据迁移（< 10k 行）→ 在迁移中同步执行
• 数据迁移（> 1M 行）→ 后台工作进程模式

需要规划回滚？

• 仅新增架构 → 简单的 DOWN 迁移
• 修改／移除架构 → 多阶段回滚或向前修复
• 不能丢失数据 → 时间点恢复（PITR）

如何选择迁移工具？

• Python/Django → Django Migrations
• Python/SQLAlchemy → Alembic
• Node.js/TypeScript → Prisma Migrate 或 Knex.js
• 企业级／多语言 → Flyway 或 Liquibase

→ 如需全面的决策框架，请参阅 references/decision-trees.md

故障排除

常见问题速查

迁移中途失败 → 检查数据库状态，通过修复迁移向前修复

检测到架构偏移 → 使用 autogenerate 创建协调迁移

无法回滚（没有降级操作） → 创建反向迁移或向前修复

违反外键约束 → 添加约束前清理数据，或将其添加为 NOT VALID

迁移锁定表的时间过长 → 使用 CONCURRENTLY，分阶段添加列，批量更新

循环依赖 → 创建合并迁移或重新排列依赖项

→ 如需包含示例的详细解决方案，请参阅 references/troubleshooting.md

导航

详细参考资料

• 🌳 决策树 - 架构迁移策略、零停机模式、回滚策略、迁移工具选择和数据迁移方法。规划迁移或选择策略时加载。

• 🔧 故障排除 - 迁移失败恢复、架构偏移检测、迁移冲突、回滚失败、数据完整性问题和性能问题。调试迁移问题时加载。

请记住

• 在生产数据副本上测试迁移
• 提前准备好回滚方案
• 部署期间进行监控
• 与团队沟通架构变更
• 让迁移保持小规模且专注