SQLx CLI

SQLx 的相关命令行工具，用于管理数据库、迁移以及使用 sqlx::query!() 和相关功能启用“离线”模式。

安装

使用 Rust 工具链

# supports all databases supported by SQLx
$ cargo install sqlx-cli

# only for postgres
$ cargo install sqlx-cli --no-default-features --features native-tls,postgres

# use vendored OpenSSL (build from source)
$ cargo install sqlx-cli --features openssl-vendored

# use Rustls rather than OpenSSL (be sure to add the features for the databases you intend to use!)
$ cargo install sqlx-cli --no-default-features --features rustls

用法

所有命令都需要提供数据库 URL。这可以通过使用 --database-url 命令行选项或通过在环境变量中或在当前工作目录的 .env 文件中设置 DATABASE_URL 来完成。

有关更多详细信息，请运行 sqlx <command> --help。

# Postgres
DATABASE_URL=postgres://postgres@localhost/my_database

在 DATABASE_URL 处创建/删除数据库

sqlx database create
sqlx database drop

创建和运行迁移

sqlx migrate add <name>

在 migrations/<timestamp>-<name>.sql 中创建一个新的文件。将您的数据库模式更改添加到这个新文件中。

sqlx migrate run

将正在运行的数据库的迁移历史与 migrations/ 文件夹进行比较，并运行任何尚未完成的脚本。

用户可以通过使用 --source 标志为 sqlx migrate 子命令提供迁移脚本的目录。

sqlx migrate info --source ../relative/migrations

回滚迁移

如果您想要创建可逆的迁移，并具有相应的“向上”和“向下”脚本，请在创建第一个迁移时使用 -r 标志

$ sqlx migrate add -r <name>
Creating migrations/20211001154420_<name>.up.sql
Creating migrations/20211001154420_<name>.down.sql

之后，您可以像上面一样运行这些命令

$ sqlx migrate run
Applied migrations/20211001154420 <name> (32.517835ms)

回滚操作同样适用

$ sqlx migrate revert
Applied 20211001154420/revert <name>

注意：所有后续迁移也将是可逆的。

$ sqlx migrate add <name1>
Creating migrations/20211001154420_<name>.up.sql
Creating migrations/20211001154420_<name>.down.sql

启用“离线模式”构建，使用 query!()

使用“离线模式”构建有2个步骤

1. 保存查询元数据以供离线使用
   • cargosqlx prepare
2. 构建

注意：保存查询元数据必须作为 cargo sqlx 运行。

cargo sqlx prepare

调用 prepare 将查询元数据保存到当前目录下的 .sqlx。对于使用查询宏的多个crate的工作区，传递 --workspace 标志以在仓库根目录下生成单个 .sqlx 目录。

cargo sqlx prepare --workspace

将此目录提交到版本控制，构建项目时不再需要活动的数据库连接。

cargo sqlx prepare --check
# OR
cargo sqlx prepare --check --workspace

如果 .sqlx 中的数据与当前数据库模式或项目中的查询不匹配，则退出状态将不为零。适用于持续集成。

强制在离线模式下构建

存在 DATABASE_URL 环境变量将优先于 .sqlx 的存在，这意味着如果可能，SQLx 将默认构建数据库。为了确保意外存在的 DATABASE_URL 环境变量或 .env 文件不会导致 cargo build（尝试）访问数据库，可以将 SQLX_OFFLINE 环境变量设置为 true。

如果您想将其设置为默认值，只需将其添加到您的 .env 文件中。执行 cargo sqlx prepare 仍然会做正确的事情并连接到数据库。

在特性标志后面包含查询（例如测试中的查询）

为了使 sqlx 能够找到某些特性标志或测试后面的查询，您需要通过传递参数到 cargo 来启用它们。

这是如何启用所有目标和特性。

cargo sqlx prepare -- --all-targets --all-features