SurrealDB 迁移

一款出色的 SurrealDB 迁移工具，拥有友好的 CLI 和灵活的 Rust 库，可轻松集成到任何项目中。

警告 此项目未经过生产环境测试，使用风险自负。

此项目可用于

• 作为 Rust 库

cargo add surrealdb-migrations

• 或作为 CLI

cargo install surrealdb-migrations

• 或在内置 CI 工作流程中使用，通过 GitHub Action

在市场查看 surrealdb-migrations GitHub Action

设计理念

SurrealDB Migrations 项目旨在简化 SurrealDB 数据库模式的创建和通过迁移进行数据库的演变。典型的 SurrealDB 迁移项目分为 3 类：模式、事件和迁移。

模式文件表示不超过一个 SurrealDB 表。模式列表可以看作是查询模型（在 CQRS 模式下）。schemas 文件夹可以看作是当前数据模型的视图。

事件文件表示不超过一个 SurrealDB 事件及其底层表。事件列表可以看作是命令模型（在 CQRS 模式下）。events 文件夹可以看作是更新数据模型的不同方法的视图。

迁移文件表示 SurrealDB 数据的变化。它可以是两个模式变化之间的时间点的变化。例如：当列被重命名或删除时，当表被重命名或删除时，当需要新数据（带默认值）时等...

开始使用

stateDiagram-v2
    scaffold : Scaffold a project
    changeSchema : Change schema/event
    createMigration: Create migration (data changes)
    apply : Apply to your database

    state fork_state <<fork>>
        [*] --> scaffold
        scaffold --> fork_state
        fork_state --> changeSchema
        fork_state --> createMigration

    state join_state <<join>>
        changeSchema --> join_state
        createMigration --> join_state
        join_state --> apply
        apply --> fork_state

1. 搭建

您可以通过以下命令行使用以下命令开始迁移项目

surrealdb-migrations scaffold template empty

这将创建执行迁移所需的文件夹和文件。以下 empty 模板应如下所示

• /schemas
  • script_migration.surql
• /events
• /migrations

有多个预定义模板，您可以尝试使用它们，快速开始。

2. 更改架构和/或创建数据变更迁移

创建您的迁移项目后，您就可以开始编写自己的模型。根据您之前看到的文件夹，您可以创建架构文件、事件文件和迁移文件。

架构

您可以创建表示存储在SurrealDB中的表的严格架构文件。

surrealdb-migrations create schema post --fields title,content,author,created_at,status

这将创建一个无架构的表，具有预定义的字段

DEFINE TABLE post SCHEMALESS;

DEFINE FIELD title ON post;
DEFINE FIELD content ON post;
DEFINE FIELD author ON post;
DEFINE FIELD created_at ON post;
DEFINE FIELD status ON post;

事件

您也可以以相同的方式创建事件。

surrealdb-migrations create event publish_post --fields post_id,created_at

这将定义一个具有预定义字段的表事件

DEFINE TABLE publish_post SCHEMALESS;

DEFINE FIELD post_id ON publish_post;
DEFINE FIELD created_at ON publish_post;

DEFINE EVENT publish_post ON TABLE publish_post WHEN $event == "CREATE" THEN (
    # TODO
);

迁移

在更新数据时，您可以创建迁移文件

surrealdb-migrations create AddAdminUser

例如，这将使用当天的当前日期和时间创建一个新的文件，如 20230317_153201_AddAdminUser.surql。所有迁移文件应按时间顺序列出。

3. 应用到数据库

最后，当您准备好时，可以使用以下命令将架构和迁移应用到数据库

surrealdb-migrations apply

或者在您的Rust项目中直接使用以下代码

use surrealdb_migrations::MigrationRunner;
use surrealdb::engine::any::connect;
use surrealdb::opt::auth::Root;

#[tokio::main]
async fn main() -> Result<()> {
    let db = connect("ws://127.0.0.1:8000").await?;

    // Signin as a namespace, database, or root user
    db.signin(Root {
        username: "root",
        password: "root",
    }).await?;

    // Select a specific namespace / database
    db.use_ns("namespace").use_db("database").await?;

    // Apply all migrations
    MigrationRunner::new(&db)
        .up()
        .await
        .expect("Failed to apply migrations");

    Ok(())
}

4. 重复

重复步骤2：更改架构和/或创建数据变更迁移。

预定义模板

为了帮助您快速开始，这里有一份您可以使用的预定义模板列表

您可以使用以下命令使用这些模板中的任何一个来生成项目

surrealdb-migrations scaffold template <TEMPLATE>

配置

您可以在项目的根目录中创建一个 .surrealdb 配置文件。这样，您就不必每次都设置相同的配置值。

[core]
    path = "./tests-files"
    schema = "less"

[db]
    address = "ws://127.0.0.1:8000"
    username = "root"
    password = "root"
    ns = "test"
    db = "test"

在 core 部分，您可以定义架构/迁移文件的位置，如果它不是当前文件夹。

在 db 部分，您可以定义用于访问您的SurrealDB数据库的值。可以是 url、username、password、命名空间 ns 或数据库名称 db。

以下是 .surrealdb 配置文件的定义

[core]
    # Optional
    # Type: String
    # Description: Path to the folder that contains your migration project (root folder by default)
    # Default: "."
    path

    # Optional
    # Type: "less" | "full"
    # Description: Define SCHEMALESS or SCHEMAFULL option by default when creating new table/event file
    # Default: "less"
    schema

[db]
    # Optional
    # Type: String
    # Description: Address of the surrealdb instance
    # Default: "ws://127.0.0.1:8000"
    address

    # Optional
    # Type: String
    # Description: Username used to authenticate to the surrealdb instance
    # Default: "root"
    username

    # Optional
    # Type: String
    # Description: Password used to authenticate to the surrealdb instance
    # Default: "root"
    password

    # Optional
    # Type: String
    # Description: Namespace to use inside the surrealdb instance
    # Default: "test"
    ns

    # Optional
    # Type: String
    # Description: Name of the database to use inside the surrealdb instance
    # Default: "test"
    db

回滚迁移

默认情况下，迁移是单向的。然而，回滚迁移以撤销错误可能很有趣。您将在两个地方找到回滚迁移

1. 在 /migrations/down 文件夹中，名称与您的正向迁移相同
2. 在 /migrations 中，但在正向迁移旁边有 .down.surql 扩展名

因此，具有回滚迁移的迁移项目可能看起来像这样

• /schemas
  • script_migration.surql
• /events
• /migrations
  • 20231605_205201_AddProduct.surql
  • /down
    • 20231605_205201_AddProduct.surql

或者像这样

• /schemas
  • script_migration.surql
• /events
• /migrations
  • 20231605_205201_AddProduct.surql
  • 20231605_205201_AddProduct.down.surql

如果需要在创建迁移文件时创建DOWN迁移文件，请使用以下命令

surrealdb-migrations create AddProduct --down

如果您需要，可以将所有迁移回滚到指定的一个。

surrealdb-migrations apply --down 20231605_205201_AddProduct

如果需要撤销所有迁移，请使用以下命令

surrealdb-migrations apply --down 0

数据库分支

数据库分支与版本控制系统（如Git）中的代码仓库分支类似，用于管理数据库分支。

使用数据库分支，您可以创建主数据库的独立副本或分支，以执行各种任务，例如测试新功能、实施更改或运行实验。这允许开发人员或团队在不同分支上独立工作，而不会干扰原始数据库的稳定性和完整性。

您可以在单独的分支上执行模式更改、应用新迁移或更改数据。这些更改在合并回主数据库之前是隔离的，从而更好地控制和管理数据库更改。

开发工作流程

在开发工作流程中，您有一个主数据库，其中包含项目上最新的功能。您经常同时处理多个功能或想尝试同事的工作，但无论您是否使用迁移，这都会弄乱您的开发数据库。数据库分支允许您创建主数据库的分支，处理新功能，应用模式或数据更改，然后在功能准备就绪时将您的更改合并到主数据库。

stateDiagram-v2
    main : Main branch
    createBranch : Create branch "feature-1"
    makeChanges : Make changes on "feature-1"
    merge : Merge "feature-1" on main
    remove : Remove branch "feature-1"

    [*] --> main
    main --> [*]
    main --> createBranch
    createBranch --> makeChanges
    makeChanges --> remove
    makeChanges --> merge
    remove --> [*]
    merge --> [*]

您可以通过以下命令行创建新分支

surrealdb-migrations branch new --address http://localhost:8000

您将收到如下消息

You can now use the branch with the following configuration:

ns: branches
db: bright-fold-1617

现在您可以使用ns和db属性在新生成的数据库上做出更改。完成更改后，您可以使用以下命令行将分支合并到原始分支

surrealdb-migrations branch merge bright-fold-1617 --mode all --address http://localhost:8000

有3种合并模式，每种模式都有自己的优点

生产工作流程

待定

数据库限制

此功能需要3个命名空间

• 功能
• 分支
• 分支/原始

强烈建议不要在您的SurrealDB实例中使用这些命名空间之一。

文档

# create new branch from current branch with a random name, from default ns/db
surrealdb-migrations branch new
# create new branch from current branch with a name, from default ns/db
surrealdb-migrations branch new <BRANCH_NAME>
# create new branch, from a specific ns/db
surrealdb-migrations branch new --ns <NS> --db <DB>

# review diffs between original branch and the new branch
surrealdb-migrations branch diff <BRANCH_NAME>

# commit and merge branch changes to the original branch
surrealdb-migrations branch merge <BRANCH_NAME>

# remove branch (ie. rollback)
surrealdb-migrations branch remove <BRANCH_NAME>

# list all existing branches
surrealdb-migrations branch list

# display infos of a branch
surrealdb-migrations branch status <BRANCH_NAME>
surrealdb-migrations branch <BRANCH_NAME>

示例

此项目包含示例应用程序，演示了在某些上下文中如何使用给定的surrealdb-migrations。以下是现有示例列表

让我们看看Paul Allen的贡献

感谢这些优秀的人们（emoji key）

Amar Sood 💻

Rom's 💻 🤔 🚇

Pranay Pratyush 🐛

Zafar Ansari 🤔

Tim 🤔

Matt Jackson 🐛

Lucas 🤔

本项目遵循all-contributors 规范。欢迎各种形式的贡献！

致谢

灵感来源于优秀项目

• Entity Framework
• Fluent Migrator
• kards-social by Micha de Vries @kearfy