CANYON-SQL

一个完全用 Rust 编写的多数据库 ORM。

Canyon-SQL 是一个用于同时处理多个数据库的高级抽象。它基于 async 语言特性，为用户提供一个高速、高性能的库来处理数据访问。

早期阶段免责声明

这个库仍处于 早期阶段。我们非常欢迎通过 fork + PR 的任何贡献。目前我们正在进行该项目的非常活跃的开发。

完整文档资源

有一个 work-in-progress 网页，使用 mdBook 构建，包含官方文档。在这里您可以找到有关 Canyon-SQL 的所有技术文档。您可以通过点击此链接阅读。

最重要的功能

• 异步 默认。几乎每个功能都可以并发使用。
• 使用多个数据源。您可以在同一时间查询多个数据库，甚至不同的数据库！这意味着您将能够在同一个项目中同时查询 PostgreSQL 数据库和 SqlServer 数据库。
• 基于宏。通过一些注释和配置文件，您就可以开始编写数据访问代码了。
• 允许迁移。 Canyon-SQL 包含一个 神模式，它会为您管理数据库中的每个表。您可以在 Canyon 代码中修改内部表，如更改列、设置约束等。此外，未来我们还计划允许您以编程方式操作整个服务器，如创建数据库、更改配置等，一切都在 Canyon 中完成！

支持的数据库

Canyon-SQL 目前支持以下数据库

• PostgreSQL（通过 tokio-postgres 包
• SqlServer（通过 tiberius 包

上述所有包都是基于 async 的包，符合 Canyon-SQL 的设计规范。

计划增加更多数据库引擎。

通过示例改进

让我们看看 Canyon 代码的示例！

经典的 SELECT * FROM {table_name}

let find_all_result: Result<Vec<League>, Box<dyn Error + Send + Sync>> =  League::find_all().await;

// Connection doesn't return an error
assert!(find_all_result.is_ok());
// We retrieved elements from the League table
assert!(!find_all_result.unwrap().is_empty());

对主键列进行搜索

let find_by_pk_result: Result<Option<League>, Box<dyn Error + Send + Sync>> = League::find_by_pk(&1).await;

assert!(find_by_pk_result.as_ref().unwrap().is_some());

let some_league = find_by_pk_result.unwrap().unwrap();
assert_eq!(some_league.id, 1);
assert_eq!(some_league.ext_id, 100695891328981122_i64);
assert_eq!(some_league.slug, "european-masters");
assert_eq!(some_league.name, "European Masters");
assert_eq!(some_league.region, "EUROPE");
assert_eq!(
    some_league.image_url,
    "http://static.lolesports.com/leagues/EM_Bug_Outline1.png"
);

注意 find_by_pk(...) 参数的引导引用。这个相关函数接收一个 &dyn QueryParameter<'_> 作为参数，而不是一个值。

构建更复杂的查询

为了展示 Canyon 的功能，我们将使用 SelectQueryBuilder<T>，它实现了 QueryBuilder<T> 特性，用于构建更复杂的 WHERE 条件、过滤数据和连接表。

let mut select_with_joins = LeagueTournament::select_query();
    select_with_joins
        .inner_join("tournament", "league.id", "tournament.league_id")
        .left_join("team", "tournament.id", "player.tournament_id")
        .r#where(LeagueFieldValue::id(&7), Comp::Gt)
        .and(LeagueFieldValue::name(&"KOREA"), Comp::Eq)
        .and_values_in(LeagueField::name, &["LCK", "STRANGER THINGS"]);
    // NOTE: We don't have in the docker the generated relationships
    // with the joins, so for now, we are just going to check that the
    // generated SQL by the SelectQueryBuilder<T> is the spected
    assert_eq!(
        select_with_joins.read_sql(),
        "SELECT * FROM league INNER JOIN tournament ON league.id = tournament.league_id LEFT JOIN team ON tournament.id = player.tournament_id WHERE id > $1 AND name = $2  AND name IN ($2, $3) "
    )

注意：目前，当您使用连接时，您需要创建一个新的模型，包含两个表中的列（如果您希望数据包含在这些列中），但只需遵循 CanyonMapper 的常规流程。它将尝试检索每个声明的字段的数据。如果您未声明在开放子句中的字段，在这种情况下 (*)，该字段将不会被检索。没问题。但如果您有无法与数据库中某些列映射的字段，程序将崩溃。

更多示例

如果您想查看更多示例，可以查看此存储库根目录下的 tests 文件夹。每个可用的数据库操作都在那里进行了测试，因此您可以使用它来查找上述文档中描述的操作的使用情况。

为 CANYON-SQL 做贡献

首先，感谢您考虑帮助我们进行项目。您可以查看我们的 模板指南。

但，为了总结

• 查看已打开的问题，以查看是否已存在此类问题或是否有人正在解决它。即使如此，您也可以进入并参与其中，解释您的观点，甚至帮助完成任务。
• 创建 Canyon-SQL 的分支
• 如果您已打开问题，请从存储库的基础分支（即默认分支）创建一个分支，并将其指向您的分支。
• 完成更改后，请向默认分支提交一个 PR。尽可能详细地填写提供的模板
• 等待审核。在大多数情况下，在批准您的更改之前，需要对功能进行测试

测试怎么办？

在 Canyon 中，隔离的单元测试通常以 doc-tests 的形式编写，而集成测试位于 ./tests 文件夹下

如果您想运行测试（因为这是您分叉仓库后想要做的第一件事），在运行测试之前，需要考虑以下几点。

• 目标机器上需要安装 Docker
• 如果您已经安装了 Docker，并且已经克隆或分叉了 Canyon-SQL，您可以运行我们的 docker-compose 文件 (docker/docker-compose.yml)，这将初始化一个 PostgreSQL 数据库，并将其内容放入其中，以便测试能够运行。
• 最后，一些测试是针对 MSSQL 的。我们没有找到在 Docker 启动时直接插入数据的好方法，而是运行了一个位于 tests/crud/mod.rs 的非常特殊的测试，该测试命名为 initialize_sql_server_docker_instance。当您运行此测试时，初始数据将被插入到该测试运行时创建的表中。（如果您知道更好的方法，请打开一个 issue 并让我们知道，以改进此过程！）