[Rust] Rust项目实战：使用SQLx CLI进行数据库迁移的完整指南

在 Rust Web 开发中，SQLx 以其异步支持和独特的“编译时 SQL 检查”能力而备受青睐。它允许开发者直接使用原生 SQL，同时借助 Rust 的类型系统保障查询安全，无需学习复杂的 DSL。

但在编写业务代码之前，如何搭建和有效管理数据库环境是关键的第一步。本文将带你从零开始，实操 SQLx CLI 工具的安装、PostgreSQL数据库的创建与管理，并深入讲解数据库迁移（Migration）的核心流程，为你的 Rust 后端开发项目奠定坚实的基础。

SQLx 是一个纯 Rust 编写的异步 SQL 工具包，其核心特性是在编译时检查查询语句的正确性。

安装 SQLx CLI

首先，通过 Cargo 安装 SQLx 命令行工具。为确保兼容性，建议指定 rustls 和 postgres 特性。

➜ cargo install sqlx-cli --no-default-features --features rustls --features postgres

查看 SQLx CLI 命令

安装完成后，可以使用 sqlx --help 查看所有可用命令及其功能概览。

➜ sqlx
Command-line utility for SQLx, the Rust SQL toolkit.

Usage: sqlx [OPTIONS] <COMMAND>

Commands:
  database  Group of commands for creating and dropping your database
  prepare   Generate query metadata to support offline compile-time verification
  migrate   Group of commands for creating and running migrations
  help      Print this message or the help of the given subcommand(s)

Options:
      --no-dotenv  Do not automatically load `.env` files
  -h, --help       Print help
  -V, --version    Print version

创建数据库

接下来，创建一个名为 chat 的数据库用于演示。这里使用 PostgreSQL 自带的 createdb 命令。

➜ createdb chat

安装 pgcli（可选）

pgcli 是一个功能强大的 PostgreSQL 命令行客户端，提供语法高亮和自动补全，能显著提升操作体验。可以通过 Homebrew 安装：

brew install pgcli

使用 pgcli 连接数据库

安装后，使用 pgcli 连接到我们刚创建的 chat 数据库。

➜ pgcli chat
Using local time zone Asia/Shanghai (server uses Asia/Shanghai)
Use `set time zone <TZ>` to override, or set `use_local_timezone = False` in the config
Server: PostgreSQL 17.6 (Homebrew)
Version: 4.3.0
Home: http://pgcli.com
qiaopengjun@/tmp:chat> [F2] Smart Completion: ON  [F3] Multiline: OFF  [F4] Emacs-mode  [F5] Explain: OFF

查看数据库中的表

在 pgcli 或 psql 中，可以使用 \dt 元命令列出当前数据库中的所有表。这个命令等效于执行 SELECT * FROM pg_catalog.pg_tables;。

实操示例：

qiaopengjun@/tmp:chat> \dt
+--------+------+------+-------+
| Schema | Name | Type | Owner |
|--------+------+------+-------|
+--------+------+------+-------+
SELECT 0
Time: 0.037s

Psql 常用命令速查

下表列出了在 PostgreSQL 命令行工具中常用的元命令：

命令	作用
\dt	列出所有普通表
\dv	列出视图
\di	列出索引
\ds	列出序列
\d <table>	查看指定表结构
\l	列出所有数据库
\c dbname	切换数据库
\dn	列出 schema

了解 sqlx migrate 命令

sqlx migrate 是 SQLx 提供的核心数据库迁移工具，用于管理数据库结构的版本化变更。

➜ sqlx migrate
Group of commands for creating and running migrations

Usage: sqlx migrate <COMMAND>

Commands:
  add           Create a new migration with the given description
  run           Run all pending migrations
  revert        Revert the latest migration with a down file
  info          List all available migrations
  build-script  Generate a `build.rs` to trigger recompilation when a new migration is added
  help          Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

创建迁移文件

使用 migrate add 命令创建一个新的迁移文件，描述为 “initial”。

➜ sqlx migrate add initial
Creating migrations/20251203080702_initial.sql

命令执行后，会在项目根目录下生成 migrations 文件夹和对应的 SQL 文件。

├── migrations
│   └── 20251203080702_initial.sql

你需要在此文件中编写 CREATE TABLE 等 SQL 语句，定义此次迁移要执行的操作。

执行数据库迁移

编写完 SQL 脚本后，使用 migrate run 命令执行所有待处理的迁移，将表结构变更应用到数据库。

➜ sqlx migrate run
Applied 20251203080702/migrate initial (23.433375ms)

验证迁移结果

再次连接数据库，使用 \dt 命令查看，可以发现新增了业务表以及 SQLx 用于记录迁移历史的 _sqlx_migrations 表。

qiaopengjun@/tmp:chat> \dt
+--------+------------------+-------+----------+
| Schema | Name             | Type  | Owner    |
|--------+------------------+-------+----------|
| public | _sqlx_migrations | table | postgres |
| public | chats            | table | postgres |
| public | messages         | table | postgres |
| public | users            | table | postgres |
+--------+------------------+-------+----------+

查询 _sqlx_migrations 表可以查看已执行的迁移记录。

qiaopengjun@/tmp:chat> select * FROM _sqlx_migrations;

总结

通过以上步骤，我们完成了 Rust 项目中围绕 数据库/中间件 的基础设施搭建。整个过程涵盖了从安装 sqlx-cli、配置数据库，到使用迁移工具进行版本化管理的完整工作流。这套基于 Migration 的实践是现代 后端开发 中管理数据库模式变更的标准方法，为团队协作和持续集成部署提供了可靠保障。掌握这些工具后，你就可以专注于在 Rust 中实现业务逻辑了。

参考

• SQLx GitHub 仓库
• SQLx CLI 子目录
• Axum Web 框架
• pgcli 官方网站