Aqueduct数据库迁移实战：从零到部署的完整工作流

【免费下载链接】aqueduct Dart HTTP server framework for building REST APIs. Includes PostgreSQL ORM and OAuth2 provider. 项目地址: https://gitcode.com/gh_mirrors/aq/aqueduct

什么是Aqueduct数据库迁移？

Aqueduct是一个强大的Dart HTTP服务器框架，内置PostgreSQL ORM和OAuth2提供程序。数据库迁移是Aqueduct应用开发中的关键环节，它帮助开发者安全地更新数据库结构，同时保留现有数据。本文将详细介绍Aqueduct数据库迁移的完整工作流程，从环境准备到部署上线，让你轻松掌握这一必备技能。

准备工作：环境搭建与项目初始化

安装Aqueduct CLI

首先，确保你的开发环境中已经安装了Dart SDK。然后通过以下命令安装Aqueduct CLI：

pub global activate aqueduct

创建新项目

使用Aqueduct CLI创建一个新的项目，我们将以数据库项目模板为例：

aqueduct create -t db my_project
cd my_project

这个命令会创建一个包含数据库支持的项目结构，其中包括模型定义和迁移相关的文件。

数据库迁移核心命令解析

Aqueduct提供了一系列强大的CLI命令来管理数据库迁移。这些命令位于项目的aqueduct/lib/src/cli/commands目录下，主要包括：

1. 生成迁移文件

当你修改数据模型后，需要生成迁移文件来反映这些变化。使用以下命令：

aqueduct db generate "描述迁移内容"

这个命令会在项目中创建一个新的迁移文件，文件名格式为00000001_描述内容.migration.dart。迁移文件的版本号会自动递增，确保迁移的顺序正确。

2. 执行迁移

生成迁移文件后，使用以下命令将迁移应用到数据库：

aqueduct db upgrade

这个命令会执行所有尚未应用的迁移文件，将数据库 schema 更新到最新版本。如果是新数据库，它会直接应用所有迁移；如果是现有数据库，它会从当前版本升级到最新版本。

3. 验证迁移

在部署前，验证迁移的正确性非常重要。使用以下命令检查迁移文件与当前代码中的模型是否一致：

aqueduct db validate

这个命令会比较迁移文件生成的 schema 与当前代码中的模型定义，确保它们一致。如果发现不一致，会显示详细的错误信息。

4. 查看迁移状态

要查看所有迁移文件的版本和状态，可以使用：

aqueduct db show

这个命令会列出所有迁移文件及其版本号，帮助你跟踪迁移进度。

迁移文件结构与编写

迁移文件是Aqueduct数据库迁移的核心。每个迁移文件都是一个Dart类，继承自Migration类，并重写upgrade方法。下面是一个典型的迁移文件结构：

import 'package:aqueduct/aqueduct.dart';

class _$MyMigration extends Migration {
  @override
  Future upgrade() async {
    // 在这里编写数据库结构变更代码
    database.createTable(SchemaTable(
      "users",
      [
        SchemaColumn("id", ManagedPropertyType.bigInteger, isPrimaryKey: true),
        SchemaColumn("name", ManagedPropertyType.string),
        SchemaColumn("email", ManagedPropertyType.string, isUnique: true),
      ],
    ));
  }

  @override
  Future downgrade() async {
    // 在这里编写回滚代码
    database.deleteTable("users");
  }

  @override
  Future seed() async {
    // 在这里编写初始数据填充代码
    await database.store.execute("INSERT INTO users (name, email) VALUES ('Admin', 'admin@example.com')");
  }
}

常用的迁移操作

Aqueduct的SchemaBuilder类提供了丰富的方法来修改数据库结构，主要包括：

• 创建表：createTable(SchemaTable table)
• 重命名表：renameTable(String currentName, String newName)
• 删除表：deleteTable(String tableName)
• 添加列：addColumn(String tableName, SchemaColumn column)
• 删除列：deleteColumn(String tableName, String columnName)
• 重命名列：renameColumn(String tableName, String currentName, String newName)
• 修改列：alterColumn(String tableName, SchemaColumn column)

这些方法会生成相应的SQL命令，确保数据库结构的正确变更。

完整迁移工作流

1. 定义数据模型

首先，在lib/model/目录下定义你的数据模型。例如，创建user.dart：

import 'package:aqueduct/aqueduct.dart';

class User extends ManagedObject<_User> implements _User {}

class _User {
  @primaryKey
  int id;

  String name;

  @Column(unique: true)
  String email;

  String passwordHash;
}

2. 生成初始迁移

运行以下命令生成初始迁移：

aqueduct db generate "initial schema"

这会创建一个包含创建users表的迁移文件。

3. 应用迁移到数据库

aqueduct db upgrade

这会在数据库中创建users表。

4. 修改数据模型

随着项目发展，你可能需要修改数据模型。例如，给User添加一个age字段：

class _User {
  // ... 现有字段 ...
  
  int age;
}

5. 生成新的迁移

aqueduct db generate "add age column to users"

这会创建一个新的迁移文件，包含添加age列的操作。

6. 验证迁移

aqueduct db validate

确保新的迁移与当前模型一致。

7. 再次应用迁移

aqueduct db upgrade

将新的迁移应用到数据库，添加age列。

8. 部署前检查

在部署到生产环境前，再次运行验证命令，确保所有迁移都正确无误：

aqueduct db validate

迁移最佳实践

1. 定期备份数据库

在执行迁移前，尤其是在生产环境中，一定要备份数据库。虽然迁移工具设计得很安全，但意外情况仍然可能发生。

2. 编写回滚代码

始终为每个迁移编写downgrade方法，以便在需要时能够回滚到之前的版本。

3. 测试迁移

在开发环境中充分测试迁移，包括升级和回滚操作，确保它们不会破坏数据。

4. 保持迁移文件的整洁

每个迁移应该只包含相关的变更，避免一次迁移做太多事情。这样可以简化问题排查和回滚操作。

5. 记录迁移

为每个迁移文件提供清晰的描述，说明它做了什么变更。这有助于团队协作和日后维护。

常见问题与解决方案

1. 迁移冲突

如果两个开发者同时修改了同一个模型并生成了迁移，可能会导致迁移冲突。解决方法是合并模型变更，然后生成一个新的迁移文件，废弃原来的两个迁移。

2. 数据丢失风险

某些操作（如删除列或表）可能导致数据丢失。在执行这类迁移前，确保已经备份了相关数据，或者在迁移中添加数据迁移代码。

3. 迁移执行失败

如果迁移执行失败，首先查看错误信息，然后根据情况修复问题。如果需要回滚，可以使用downgrade方法（如果已实现）。

4. 生产环境迁移策略

在生产环境中执行迁移时，建议先在 staging 环境测试，然后在低峰期执行，并准备好回滚方案。

总结

Aqueduct提供了一套强大而灵活的数据库迁移工具，使开发者能够安全、高效地管理数据库结构变更。通过遵循本文介绍的工作流程和最佳实践，你可以确保数据库迁移过程顺利进行，减少风险，提高开发效率。

无论是小型项目还是大型应用，掌握Aqueduct数据库迁移都是每个Dart后端开发者必备的技能。希望本文能帮助你更好地理解和应用Aqueduct的迁移功能，构建更健壮的应用。

记住，良好的迁移习惯不仅能保证数据安全，还能提高团队协作效率，为项目的长期发展奠定坚实基础。现在就开始在你的Aqueduct项目中实践这些技巧吧！

【免费下载链接】aqueduct Dart HTTP server framework for building REST APIs. Includes PostgreSQL ORM and OAuth2 provider. 项目地址: https://gitcode.com/gh_mirrors/aq/aqueduct