编辑“︁Next.js数据库迁移”︁

= Next.js数据库迁移 =

== 介绍 ==
数据库迁移（Database Migration）是开发过程中管理数据库结构变更的核心技术，尤其在Next.js全栈应用中，它允许开发者以版本控制的方式同步数据库架构与应用程序演进。本章将系统讲解如何在Next.js项目中规划、执行和回滚数据库迁移。

== 核心概念 ==
'''数据库迁移'''指通过脚本文件记录数据库结构（如表、字段、索引）的变更历史，其核心特征包括：
* '''版本化控制'''：每个迁移文件对应唯一的版本标识
* '''可逆性'''：可执行升级（up）或降级（down）操作
* '''一致性'''：确保开发/生产环境数据库结构一致

=== 迁移工具对比 ===
{| class="wikitable"
|+ Next.js常用迁移工具对比
! 工具 !! 适用数据库 !! 特点
|-
| Prisma Migrate || PostgreSQL/MySQL/SQLite || 声明式架构定义
|-
| TypeORM Migrations || 多种关系型数据库 || 基于TypeScript的迁移脚本
|-
| Knex.js || 支持12+种数据库 || 灵活的SQL构建器
|}

== 实现方案 ==

=== 方案1：Prisma Migrate ===
1. 初始化迁移配置：
<syntaxhighlight lang="bash">
npx prisma migrate dev --name init
</syntaxhighlight>

2. 典型迁移文件示例（自动生成）：
<syntaxhighlight lang="prisma">
// 迁移描述
model User {
  id    Int     @id @default(autoincrement())
  name  String
  email String  @unique
}
</syntaxhighlight>

3. 执行迁移：
<syntaxhighlight lang="bash">
npx prisma migrate deploy
</syntaxhighlight>

=== 方案2：TypeORM迁移 ===
1. 创建迁移文件：
<syntaxhighlight lang="typescript">
// src/migrations/1234567890-CreateUserTable.ts
import { MigrationInterface, QueryRunner } from "typeorm";

export class CreateUserTable implements MigrationInterface {
    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`
            CREATE TABLE "user" (
                "id" SERIAL PRIMARY KEY,
                "name" VARCHAR(100) NOT NULL,
                "email" VARCHAR(255) UNIQUE NOT NULL
            )`);
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`DROP TABLE "user"`);
    }
}
</syntaxhighlight>

2. 运行迁移：
<syntaxhighlight lang="json">
// package.json
{
  "scripts": {
    "typeorm": "typeorm-ts-node-commonjs",
    "migrate": "npm run typeorm migration:run"
  }
}
</syntaxhighlight>

== 迁移生命周期 ==
<mermaid>
stateDiagram-v2
    [*] --> 创建迁移文件
    创建迁移文件 --> 测试环境验证
    测试环境验证 --> 生产环境部署
    生产环境部署 --> 版本回滚(可选)
    版本回滚(可选) --> [*]
</mermaid>

== 最佳实践 ==
1. '''原子性变更'''：每个迁移应只完成一个逻辑变更
2. '''数据备份'''：执行生产环境迁移前必须备份
3. '''环境隔离'''：开发/测试/生产环境使用独立数据库实例
4. '''回滚测试'''：验证down脚本的正确性

数学表达迁移成功率公式：
<math>
P_{success} = 1 - \prod_{i=1}^{n}(1 - R_i)
</math>
其中<math>R_i</math>表示单个迁移步骤的可靠性

== 实战案例 ==
'''电商平台用户系统升级'''
1. 初始状态：users表仅有id/name字段
2. 需求变更：需要添加手机号认证
3. 迁移过程：
<syntaxhighlight lang="sql">
-- 升级脚本
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
CREATE INDEX idx_users_phone ON users(phone);

-- 回滚脚本
DROP INDEX idx_users_phone;
ALTER TABLE users DROP COLUMN phone;
</syntaxhighlight>

== 常见问题 ==
'''Q：如何解决多开发者的迁移冲突？'''
A：采用时间戳前缀的迁移文件名（如20230815-xxx），合并时按时间顺序执行

'''Q：生产环境迁移失败如何处理？'''
A：立即执行回滚脚本，检查错误日志后重新设计迁移方案

== 进阶技巧 ==
* '''数据迁移'''与结构迁移分离处理
* 使用事务包裹DDL操作（部分数据库支持）
* 利用迁移工具提供的钩子函数（before/after迁移）

通过系统化的迁移管理，Next.js项目可以确保数据库结构与代码演进保持同步，为应用迭代提供可靠的数据层支持。

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js数据库集成]]