如何在Rust应用中运行sqlx迁移并解决编译与安装问题

1. 解决编译时表不存在的核心问题 #

SQLx默认会在编译阶段验证查询与数据库表结构的匹配性，这就是迁移未执行就报错relation "order_events" does not exist的原因。有两种实用修复方式：

方式A：启用离线编译模式 #

通过环境变量SQLX_OFFLINE=true让SQLx跳过编译时的数据库连接校验，依赖本地生成的sqlx-data.json文件（需先在本地完成迁移和预处理）：

• 本地提前执行：

  sqlx migrate run
  cargo sqlx prepare --workspace
  

• 编译/运行时添加环境变量：

  SQLX_OFFLINE=true cargo run
  

• Docker或流水线中，将sqlx-data.json加入镜像，编译时设置该变量即可跳过校验。

方式B：改用运行时查询宏 #

把编译时验证的sqlx::query!/sqlx::query_as!替换为运行时版本的sqlx::query/sqlx::query_as，避免编译阶段检查表结构：

// 替换前（编译时验证）
let events = sqlx::query_as!(OrderEvent, "SELECT * FROM order_events")
    .fetch_all(&pool)
    .await?;

// 替换后（运行时验证）
let events = sqlx::query_as::<_, OrderEvent>("SELECT * FROM order_events")
    .fetch_all(&pool)
    .await?;

2. 修复Docker中SQLx-CLI安装失败的问题 #

Docker基础镜像默认缺少OpenSSL系统依赖，需在安装sqlx-cli前先安装对应包：

Debian/Ubuntu系镜像示例 #

# 构建阶段
FROM rust:1.78-slim-bookworm AS builder

# 安装系统依赖（OpenSSL + Postgres客户端）
RUN apt-get update && apt-get install -y --no-install-recommends \
    libssl-dev \
    pkg-config \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 安装sqlx-cli
RUN cargo install sqlx-cli --no-default-features --features postgres

# 复制项目文件并预处理
WORKDIR /app
COPY . .
RUN sqlx migrate run && cargo sqlx prepare --workspace

# 编译应用
RUN cargo build --release

# 运行阶段（精简镜像）
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    libssl3 \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=builder /app/target/release/your-api-name .
COPY --from=builder /app/migrations ./migrations
COPY --from=builder /app/sqlx-data.json ./sqlx-data.json

# 启动时先执行迁移再启动应用
CMD ["sh", "-c", "sqlx migrate run && ./your-api-name"]

Alpine系镜像示例 #

Alpine依赖包名不同，调整安装命令：

FROM rust:1.78-alpine AS builder
RUN apk add --no-cache \
    openssl-dev \
    pkgconfig \
    postgresql-dev \
    musl-dev

RUN cargo install sqlx-cli --no-default-features --features postgres
# 后续复制文件、编译步骤同上...

3. 流水线构建的正确流程 #

流水线需确保迁移执行在编译之前，或使用离线编译模式，以下是通用步骤：

步骤1：启动Postgres服务 #

以GitHub Actions为例：

services:
  postgres:
    image: postgres:15
    env:
      POSTGRES_USER: your_user
      POSTGRES_PASSWORD: your_pass
      POSTGRES_DB: your_db
    ports:
      - 5432:5432
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

步骤2：执行迁移并生成预处理文件 #

# 安装sqlx-cli（若流水线镜像未预装）
cargo install sqlx-cli --no-default-features --features postgres

# 设置数据库连接字符串
export DATABASE_URL=postgres://your_user:your_pass@localhost:5432/your_db

# 执行迁移
sqlx migrate run

# 生成sqlx-data.json用于离线编译
cargo sqlx prepare --workspace

步骤3：编译并部署应用 #

SQLX_OFFLINE=true cargo build --release
# 后续部署步骤...

额外建议 #

• 将sqlx-data.json加入版本控制，本地迁移或查询逻辑变更后，重新执行cargo sqlx prepare更新文件，流水线可直接复用。
• 生产环境建议把迁移步骤与应用启动分离，比如用Kubernetes Job单独执行迁移，再启动应用Pod，避免重复执行迁移。

内容的提问来源于stack exchange，提问作者Sathya