문서가격블로그
문의하기
로그인무료로 가입하기
Back to Tech Articles

オフラインスキーマ管理：堅牢なRustアプリケーションのためのsqlx-cliとdiesel-cliの活用

10월 01, 2025
# Misc

Wenhao Wang

Dev Intern · Leapcell

이 게시물은 English, 한국어 및 Deutsch에서도 볼 수 있습니다.
Cover of "オフラインスキーマ管理：堅牢なRustアプリケーションのためのsqlx-cliとdiesel-cliの活用"

はじめに

現代のソフトウェア開発の世界では、データベースはほぼすべてのアプリケーションの基盤です。アプリケーションが進化するにつれて、そのデータ構造も進化します。データベースマイグレーションとして知られるこれらの変更を管理することは、アプリケーションの安定性、保守性、およびデプロイ可能性に直接影響を与える重要なタスクです。Rustのエコシステムでは、強力な型付けとコンパイル時の保証が重視されているため、アプリケーションのデータモデルとデータベーススキーマを同期させることが最も重要です。マイグレーションを管理するためのツールは数多く存在しますが、ライブデータベース接続なしでオフラインスキーマチェックを実行し、マイグレーションを管理できる機能は、特にCI/CDパイプラインや厳格なネットワークアクセスを持つローカル開発環境において、大きな利点を提供します。この記事では、Rust開発者がsqlx-cliやdiesel-cliのような強力なコマンドラインツールを活用して、データベースマイグレーションとスキーマを効果的に管理する方法について、特にその貴重なオフライン機能に焦点を当てて掘り下げます。

環境の理解

sqlx-cliとdiesel-cliの詳細に入る前に、Rustにおけるデータベーススキーマ管理の根底にあるいくつかのコアコンセプトを明確にしましょう。

  • データベースマイグレーション: これらはデータベーススキーマに対するプログラムによる変更です。通常、データベースをある状態から別の状態に進化させる方法（新しいテーブルの追加、列の変更、インデックスの作成など）を定義するバージョン管理されたファイル（例：SQLスクリプトまたはRustコード）です。
  • スキーマ: テーブル、列、リレーションシップ、インデックス、およびデータベースのその他の要素の正式な記述です。
  • ORM（オブジェクトリレーショナルマッパー）: オブジェクト指向プログラミング言語を使用して、互換性のない型システム間のデータを変換するプログラミング技術です。Rustでは、Dieselが著名なORMです。
  • クエリビルダー: 開発者がプログラムでSQLクエリを構築できるライブラリで、多くの場合、型安全性を提供し、生のSQL文字列を回避します。SQLxは主にクエリビルダーであり、非同期データベースドライバーです。
  • オフラインスキーマチェック: ライブデータベース接続を必要とせずに、アプリケーションのデータモデル（例：Rustの構造体）とデータベーススキーマとの間の不一致を検証したり、マイグレーションファイルを生成したりする機能です。これにより、開発が大幅に高速化され、CI/CDの効率が向上します。

SQLxとDieselはどちらもRustでデータベースと対話するための堅牢なソリューションを提供しており、それぞれのCLIツールはスキーマ管理にまでその機能性を拡張しています。DieselはRustコード内での型安全なクエリとスキーマ定義に焦点を当てたORMである一方、SQLxは型安全な生のSQLクエリと、スキーマ定義に対するよりハンズオフなアプローチを重視しています。しかし、どちらも最新の開発に不可欠な強力なマイグレーションユーティリティを提供しています。

sqlx-cli：型安全なSQLとオフラインチェック

sqlx-cliは、SQLxデータベースクレートのコマンドラインインターフェースです。SQLxは、生のSQLクエリのコンパイル時チェックで知られており、アプリケーションを実行する前にクエリが構文的に正しく、データベーススキーマと一致していることを保証します。ここでsqlx-cliが、特にオフラインのsqlx database diffおよびsqlx migrate add機能で輝きます。

sqlx-cliは、基本的にSQLスクリプトファイルを通じてマイグレーションを管理します。sqlx-cliを使用した典型的なマイグレーションワークフローには、以下が含まれます。

  1. 新しいマイグレーションの作成：

    sqlx migrate add create_users_table

    このコマンドは、指定されたマイグレーションディレクトリ（通常はmigrations/）に、マイグレーションの適用と元に戻すための_up.sqlおよび_down.sqlサフィックスを持つ新しいマイグレーションファイルを生成します。

  2. マイグレーションSQLの記述： 次に、これらのファイルにSQL DDLステートメントを記述します。

    -- migrations/20231027100000_create_users_table.up.sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username VARCHAR(255) NOT NULL UNIQUE,
  email VARCHAR(255) NOT NULL UNIQUE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
    -- migrations/20231027100000_create_users_table.down.sql
DROP TABLE users;

  3. マイグレーションの適用： 通常、以下を実行します。

    sqlx migrate run

    これにより、保留中のすべてのマイグレーションがデータベースに適用されます。

オフラインチェックの文脈におけるsqlx-cliのキラー機能は、アプリケーションのクエリをマイグレーション履歴に対して検証する機能です。SQLxは、以前のデータベース操作またはsqlx prepareによって生成された.sqlxメタデータファイルを保存します。これらのファイルは、期待されるスキーマとクエリの型をキャプチャします。新しいクエリや変更されたスキーマがある場合、sqlx prepare --checkを実行すると、SQLx DATABASE_URL環境変数がライブデータベースではなくスキーマファイルを指している場合、ライブデータベース接続なしでデータベースマイグレーションを検証し、不一致を特定できます。

または、sqlx-cli自体は、DATABASE_URLにスキーマファイルを指す必要なしに強力なオフラインチェックを提供します。Rustアプリケーションと一連のマイグレーションがあるプロジェクトを考えてみてください。CI実行ごとにデータベースを起動して、アプリケーションのクエリが期待されるスキーマに対してまだ有効であるかを確認する代わりに、sqlx-cliはマイグレーションファイルからデータベーススキーマを合成できます。

# このコマンドはオフラインで実行して、マイグレーションが有効なSQLであり、
# 明らかな構文エラーがないことを検証できます。
sqlx migrate info

sqlx-cliは主にマイグレーションの実行に焦点を当てていますが、sqlx database diffコマンドは、Rust構造体から直接オフラインスキーマ生成と比較、またはスキーマファイルで表される2つの異なるデータベース状態、またはライブデータベースの比較を目的とした強力な実験的な機能です。Rust構造体からのほとんどのオフラインスキーマ生成にはまだ成熟していませんが、その開発は、より洗練されたオフラインスキーマ管理への明確な道筋を示しています。現時点では、sqlxユーザーにとって主な「オフラインチェック」は、.sqlxメタデータファイルによって可能になるコンパイル時チェックから得られることが多く、これはSQLX_OFFLINEがtrueに設定されている場合（またはsqlx prepare --checkによって）cargo checkによって暗黙的にチェックされます。

// src/main.rs
#[macro_use]
extern crate sqlx;

#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
    // 本番アプリケーションでは、DATABASE_URLは環境変数からロードされます
    let database_url = std::env::var("DATABASE_URL")
        .expect("DATABASE_URL must be set");
    let pool = sqlx::PgPool::connect(&database_url).await?;

    let row: (i64,) = sqlx::query_as("SELECT $1 FROM users") // `users`テーブルが存在しない場合、ここでエラー
        .bind(150_i64)
        .fetch_one(&pool)
        .await?;

    println!({})
        .0;

    Ok(())
}

SQLX_OFFLINE=trueが設定されている場合、sqlxはキャッシュされた情報を使用してクエリを検証し、cargo checkがクエリのオフラインスキーマ検証ツールとして効果的に機能します。これはCI/CDにとって信じられないほど強力な機能です。

diesel-cli：ORM主導のマイグレーションとスキーマ生成

diesel-cliは、Diesel ORMのコマンドラインツールです。Dieselはデータベース操作に異なるアプローチを取り、マクロを使用してRustコード内で直接スキーマを定義することに焦点を当てています。これにより、クエリと操作に対して高いレベルの型安全​​性を提供できます。

diesel-cliのスキーマ管理の中核は、schema.rsファイルとマイグレーションシステムを中心に展開されます。

  1. Dieselの初期化：

    diesel setup

    このコマンドは、必要なフォルダとdiesel.toml設定ファイルをセットアップします。

  2. schema.rsの生成： ここでdiesel-cliはオフライン作業で真価を発揮します。diesel-cliは、ライブデータベース接続を検査して、データベーステーブルと列のRust表現を含むsrc/schema.rsファイルを生成できます。

    diesel print-schema > src/schema.rs

    このschema.rsファイルは、Rustアプリケーション内のデータベーススキーマの単一の真実の源として機能します。しかし、この特定のコマンドはライブデータベース接続を必要とします。

    diesel-cliのオフラインパワーは、マイグレーションシステムと、schema.rsが生成されると、アプリケーションはそのファイルに対して型チェックされ、ライブデータベースではないという事実から生まれます。schema.rsをマイグレーションと最新の状態に保つことを手動で確認できます。

  3. 新しいマイグレーションの作成：

    diesel migration generate create_posts_table

    sqlx-cliと同様に、これによりマイグレーション用のup.sqlおよびdown.sqlファイルが作成されます。

  4. マイグレーションSQLの記述：

    -- migrations/20231027100000_create_posts_table/up.sql
CREATE TABLE posts (
  id SERIAL PRIMARY KEY,
  title VARCHAR NOT NULL,
  body TEXT NOT NULL,
  published BOOLEAN NOT NULL DEFAULT FALSE
);
    -- migrations/20231027100000_create_posts_table/down.sql
DROP TABLE posts;

  5. マイグレーションの適用：

    diesel migration run

    これにより、マイグレーションがデータベースに適用されます。

diesel-cliでのオフラインチェックの主なユースケースは、src/schema.rsがマイグレーションの状態を、ライブデータベースに接続せずに正確に反映していることを確認する必要がある場合に発生します。diesel print-schemaは接続を必要としますが、一時的なインメモリデータベース（SQLiteのような選択したバックエンドで利用可能なら）またはCIで起動および破棄されるDocker化されたテストデータベースに統合できます。PostgreSQLまたはMySQLの場合、これは通常、テストデータベースのセットアップを伴います。

ただし、真のオフラインパワーは、Rustコードの型安全性がschema.rsによって保証されているという事実から生まれます。schema.rsを一度生成してしまい、その後アプリケーションをビルドするだけで、Rustコンパイラはschema.rsがRust構造体と一致しなくなった場合にエラーをキャッチします。

簡単なDieselアプリケーションを考えてみましょう。

// src/schema.rs （diesel print-schemaで生成、またはマイグレーションごとに手動で維持）
diesel::table! {
    posts (id) {
        id -> Int4,
        title -> Varchar,
        body -> Text,
        published -> Bool,
    }
}

// src/models.rs
use crate::schema::posts;
use diesel::Queryable;

#[derive(Queryable)]
pub struct Post {
    pub id: i32,
    pub title: String,
    pub body: String,
    pub published: bool,
}

// src/main.rs
use diesel::prelude::*;
use diesel::pg::PgConnection;

fn main() {
    let database_url = std::env::var("DATABASE_URL")
        .expect("DATABASE_URL must be set");
    let mut connection = PgConnection::establish(&database_url)
        .expect("Error connecting to database");

    // このクエリは `src/schema.rs` に対して型チェックされます
    let results: Vec<crate::models::Post> = posts::table
        .filter(posts::published.eq(true))
        .limit(5)
        .load(&mut connection)
        .expect("Error loading posts");

    println!("Found {} published posts.", results.len());
}

マイグレーションを変更した場合（例：postsテーブルに新しい列を追加した場合）、src/schema.rsを更新しないと、Rustコードが古いschema.rsに依存している場合、cargo buildまたはcargo checkは失敗する可能性が高いです。その後、一時的なデータベースでマイグレーションを実行し、src/schema.rsを再生成することでスキーマ変更を再評価できます。このプロセスにより、ライブで運用可能なデータベースインスタントが常に利用可能である必要なしに、整合性が保証されます。

CI/CDの場合、diesel migration checkコマンドは、schema.rsファイルを、すべてのマイグレーションが実行された場合に生成されるものと比較し、不一致をフラグ付けできます。

# このコマンドは、マイグレーションを実行してスキーマを比較するために
# データベース接続を必要としますが、インメモリまたは一時的なDBを指すことができます。
diesel migration check

真のオフラインチェックは、schema.rsが目的のスキーマを反映して生成された後のcargo-checkから得られます。schema.rsによって記述されたデータベースとRust構造体の相互作用の方法からの逸脱は、コンパイルエラーにつながります。

結論

sqlx-cliとdiesel-cliはどちらもRustでのデータベースマイグレーションとスキーマ管理のための堅牢なソリューションを提供します。sqlx-cliは、既存のデータベースまたは独自のメタデータから派生したスキーマに対して生のSQLクエリのコンパイル時チェックを行うのに優れており、SQLxユーザーに強力な「オフライン」クエリ検証を提供します。一方、diesel-cliはORMアプローチを活用してschema.rsファイルを生成し、そのファイルに対してRustコードが型チェックされます。ライブデータベース接続が永続的に利用できないシナリオであっても、これらのツールでスキーマとマイグレーションを管理および検証できる機能は、開発ワークフローを大幅に合理化し、CI/CDパイプラインを強化し、最終的により信頼性の高いRustアプリケーションにつながります。これらのCLIツールを習得することは、データベース駆動型アプリケーションを構築するすべてのRust開発者にとって不可欠です。

Share this article

HackerNews

More Posts from Leapcell

Popular Posts