--- title: "SQLx CLI（sqlx-cli）の使い方｜sqlx migrateとcargo sqlx prepareを0.9.0で実行して解説" url: "https://www.issoh.co.jp/tech/details/2901/" published: 2024-07-03 updated: 2026-10-27 categories: ["Rust"] publisher: "株式会社一創" --- # SQLx CLI（sqlx-cli）の使い方｜sqlx migrateとcargo sqlx prepareを0.9.0で実行して解説 SQLx CLI（`sqlx-cli`）は、RustのSQLxクレートに付属するコマンドラインツールです。データベースの作成、マイグレーションの作成と適用、そしてデータベースに接続せずにビルドするための`cargo sqlx prepare`を受け持ちます。この記事では、現行版のsqlx-cli 0.9.0を検証環境（macOS・Rust 1.99.1・PostgreSQL 18.6）でビルドし、各コマンドを実行したときの出力をそのまま載せています。同じ名前のGoの`jmoiron/sqlx`は別のライブラリで、CLIもマイグレーション機能も持たないため、この記事の対象外です。 ## まとめ：sqlx-cli 0.9.0のコマンド早見と押さえる3点 | コマンド | 用途 | | -------------------------------- | ---------------------- | | cargo install sqlx-cli | CLI本体の導入 | | sqlx database create ／ drop | DATABASE\_URLのDBを作成・削除 | | sqlx database setup ／ reset | 作成＋全マイグレーション適用／作り直し | | sqlx migrate add -r 名前 | up・downの対でファイルを作成 | | sqlx migrate run ／ info ／ revert | 適用・状態確認・1つ巻き戻し | | sqlx migrate build-script | migrate!用のbuild.rsを生成 | | cargo sqlx prepare | .sqlxにクエリ情報を保存 | | `cargo sqlx prepare --check` | キャッシュ不足・内容不一致でexit 1 | - **適用済みのマイグレーションファイルは書き換えない**。書き換えると`sqlx migrate run`が`was previously applied but has been modified`で止まり、終了コード1を返します。 - **`query!`系マクロを使うなら`.sqlx`をコミットし、CIで`cargo sqlx prepare --check`を回す**。DBの無いビルド環境でも`SQLX_OFFLINE=true`でコンパイルできます。 - **0.9.0では`--locked`を前提にしない**。公式のCHANGELOGがリポジトリでの`Cargo.lock`管理をやめたと告知しており、検証環境では`--locked`で取り下げ済み（yanked）の依存4件の警告が出ました。 ## sqlx-cliのインストールと接続設定 ### cargo installとfeatureの選び方 sqlx-cliは`cargo install`で入れます。Rust自体の導入や`cargo install`の仕組みは[Cargo（Rust）とは？インストールとcargo installの使い方・主要コマンド一覧](/tech/details/9572/)にまとめています。0.9.0の動作に必要なRustは1.94.0以上です（crates.ioの`rust-version`）。 ``` cargo install sqlx-cli ``` 既定のfeatureは`postgres`・`sqlite`・`mysql`・`native-tls`・`completions`・`sqlx-toml`です（[sqlx-cliのCargo.toml](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/Cargo.toml)）。全部入りのビルドは検証環境で3分58秒かかり、`sqlx`と`cargo-sqlx`の2つのバイナリが入りました。使うDBが1つなら、既定を切って絞るとビルドが軽くなります。 ``` cargo install sqlx-cli --no-default-features --features rustls,postgres ``` `postgres`の代わりに`mysql`・`sqlite`を指定でき、カンマ区切りで併記もできます。OS側のSQLiteライブラリを使うなら`sqlite-unbundled`、OpenSSLをソースからビルドするなら`openssl-vendored`を選びます。0.9.0で追加された`mysql-rsa`は、TLSを使わずに`caching_sha2_password`または`sha256_password`認証でRSA鍵交換を必要とするMySQL・MariaDBへ接続する場合に必要です（[sqlx-cli README](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/README.md)）。導入後は`sqlx --version`で`sqlx-cli 0.9.0`と表示されることを確かめ、アプリ側のsqlxクレートと版を揃えます。 ### sqlx-cli 0.9.0で`--locked`を付けない理由 0.8系までの解説では`cargo install sqlx-cli --locked`がよく勧められていました。0.9.0の[CHANGELOG](https://github.com/transact-rs/sqlx/blob/main/CHANGELOG.md)は、リポジトリでの`Cargo.lock`の追跡をやめたことを告知し、`cargo install --locked sqlx-cli`は今後機能しなくなると書いています。再現性のあるビルドが必要なら自前でロックファイルを持つよう案内しています。 検証環境で`--locked`付きのインストールを実行すると、ビルドそのものは成功しましたが、次の警告が4件（chacha20 0.10.0、crypto-bigint 0.7.3、der 0.8.0、spin 0.9.8）出ました。 ``` warning: package `chacha20 v0.10.0` in Cargo.lock is yanked in registry `crates-io` | = help: consider running without --locked ``` 取り下げ済みの版で固定されるため、0.9.0では`--locked`を付けない通常の`cargo install sqlx-cli`を使うのが公式の案内に沿った入れ方です。CIで版を固定したいときは`--version 0.9.0`で版番号を指定します。 ### DATABASE\_URLと.envの読み込み ほぼすべてのコマンドが接続先を必要とします。指定方法は`-D`（`--database-url`）オプション、環境変数`DATABASE_URL`、カレントディレクトリの`.env`の3通りです。どれも無いと次のエラーで終了コード1になります。 ``` $ sqlx migrate info error: `--database-url` or `DATABASE_URL` must be set ``` ``` DATABASE_URL=postgres://postgres@localhost:5432/app ``` `.env`を読むのはsqlx-cliと、コンパイル時にスキーマを問い合わせる`query!`系マクロです。ビルドしたアプリが実行時に`.env`を読むわけではありません。検証で`std::env::var("DATABASE_URL")`を使うアプリを`.env`だけ置いて`cargo run`すると、`Error: NotPresent`で終了しました。実行時にも`.env`を使うなら`dotenvy`クレートで読み込むか、環境変数を渡します。CLIに`.env`を読ませたくない場面では`--no-dotenv`を付けます。 ## SQLxクレートの依存追加とfeature設定 アプリからSQLを実行するには、CLIとは別にsqlxクレートを依存に加えます。 ``` cargo add sqlx@=0.9.0 --features runtime-tokio,tls-rustls,postgres cargo add tokio --features full ``` 0.9.0の既定featureは`any`・`macros`・`migrate`・`json`で、`query!`マクロと`migrate!`マクロは追加指定なしで使えます。オフラインモード用の`offline`機能は`macros`に含まれるため、古い記事にある`features = ["offline"]`の追記は不要です。ランタイムとTLSは`runtime-tokio`と`tls-rustls`のように別々に指定します。`runtime-tokio-rustls`のような結合名は0.9.0で削除されました。`tls-rustls`は暗号にring、ルート証明書に同梱のwebpkiを使う構成の別名で、AWS-LCを使うなら`tls-rustls-aws-lc-rs`、OSの証明書ストアを使うなら`tls-rustls-ring-native-roots`を選びます。SQLxは非同期APIなので`#[tokio::main]`などのランタイムが要ります。非同期の基礎は[Rustのasync/await入門｜Futureとpollの仕組み、Tokioでの実行とよくあるエラー](/tech/details/8681/)で確認できます。 ## sqlx migrateによるマイグレーション管理 ### sqlx databaseによるDBの作成・再作成 `sqlx database create`は`DATABASE_URL`のDBを作り、成功しても何も表示しません。`setup`は作成と未適用マイグレーションの適用を一度に行い、`reset`は削除・再作成・適用までを行います。 ``` $ sqlx database setup Applied 20261027053727/migrate create users (23.063217ms) Applied 20261027053737/migrate add email (1.015279ms) ``` `drop`と`reset`は確認のプロンプトを出します。端末の無いCIで`-y`を付けずに実行すると、`Confirm dialog failed with IO error: not a terminal`でパニックし、終了コード101になりました。CIでは`sqlx database reset -y`のように必ず`-y`を付けます。SQLiteでは`-D sqlite:app.db`のように指定すると、`create`がファイルを作ります。 ### sqlx migrate addによるファイル生成と採番 `-r`を付けると、同じ版番号の`.up.sql`（適用用）と`.down.sql`（巻き戻し用）が対で作られます。 ``` $ sqlx migrate add -r create_users Creating migrations/20261027053727_create_users.up.sql Creating migrations/20261027053727_create_users.down.sql ``` ``` CREATE TABLE users ( id BIGSERIAL PRIMARY KEY, name TEXT NOT NULL ); ``` down側には`DROP TABLE users;`を書きます。`-r`を付けない`add`は、直前のマイグレーションの形式に合わせます。最新が可逆なら、`sqlx migrate add add_email`でも`.up.sql`と`.down.sql`の対が作られました。前進のみの`.sql`1本にしたいときは`--simple`を付けます。版番号は既定で`YYYYMMDDHHMMSS`のタイムスタンプです。`-s`（`--sequential`）を付けると1・2・3の連番になり、直近2本の版番号の差が1なら連番が自動で続きます。 ### sqlx migrate run・info・revertの実行結果 `info`は各マイグレーションの状態を`pending`（未適用）か`installed`（適用済み）で示します。`run --dry-run`は適用せずに対象だけを表示します。 ``` $ sqlx migrate info 20261027053727/pending create users $ sqlx migrate run --dry-run Can apply 20261027053727/migrate create users (0ns) $ sqlx migrate run Applied 20261027053727/migrate create users (24.70484ms) $ sqlx migrate info 20261027053727/installed create users ``` `revert`は最後の1本だけを戻します。全部を戻すなら`--target-version 0`を指定し、新しい順に巻き戻されます。`run`にも`--target-version`があり、指定した版まで適用して止められます。 ``` $ sqlx migrate revert Applied 20261027053737/revert add email (2.172936ms) # 以下はcreate_usersとadd_emailを両方適用済みの状態から実行した別の例 $ sqlx migrate revert --target-version 0 Applied 20261027053737/revert add email (14.183771ms) Applied 20261027053727/revert create users (45.430415ms) ``` マイグレーションの置き場所を`migrations/`以外にするなら`--source ../db/migrations`のように指定します。0.9.0では`sqlx migrate override skip`（未適用分を実行せずに適用済みとして記録する）も加わりましたが、ヘルプ自体が「potentially dangerous」と注記しているため、既存DBに後からSQLxを入れる場合など目的がはっきりしているときだけ使います。 ### \_sqlx\_migrationsテーブルに記録される内容 適用履歴は`_sqlx_migrations`テーブルに残ります。PostgreSQL 18.6で列を確認した結果は次のとおりです。 | 列 | 型 | 中身 | | --------------- | ----------- | ------------------ | | version | bigint（主キー） | ファイル名先頭の版番号 | | description | text | 名前（\_を空白に置換） | | installed\_on | timestamptz | 適用日時 | | success | boolean | 成功したか | | checksum | bytea | ファイル内容のハッシュ（48バイト） | | execution\_time | bigint | 実行時間（ナノ秒） | 実測では`execution_time`が`24704840`で、CLIの表示（24.70484ms）とナノ秒単位で一致しました。`checksum`は48バイトで、この値をローカルのファイルと突き合わせるのが次の節の挙動です。複数のクレートが同じDBにマイグレーションを流す場合は、0.9.0の設定ファイル`sqlx.toml`でこのテーブル名を変えられます。 ### 適用済みマイグレーションの改変によるrunの停止 適用済みの`add_email.up.sql`の末尾にコメントを1行足しただけで、`info`はチェックサムの不一致を表示し、`run`はエラーで止まりました。 ``` $ sqlx migrate info 20261027053727/installed create users 20261027053737/installed (different checksum) add email applied migration had checksum 4b886657d12acaaa416c4a98503159bf... local migration has checksum a4593037a48a4c2c722779838978b41e... $ sqlx migrate run error: migration 20261027053737 was previously applied but has been modified $ echo $? 1 ``` 書き換えた内容が黙って捨てられるのではなく、後続の未適用分も含めて`run`全体が進まなくなります。共有DBや本番に適用済みのファイルは書き換えず、変更は新しいマイグレーションとして追加します。手元の開発DBだけなら、`revert`で戻してから直して`run`し直すか、`sqlx database reset -y`で作り直せば解消します。`git pull`で他人が書き換えたファイルを取り込んだときにもこのエラーが出るので、レビューで「適用済みファイルの差分」を止めるのが確実です。 ## sqlx::migrate!による起動時のマイグレーション適用 CLIで手動適用する代わりに、`migrations/`をバイナリに埋め込み、起動時に適用する方法もあります。[migrate!マクロ](https://docs.rs/sqlx/latest/sqlx/macro.migrate.html)は既定featureの`migrate`で使えます。 ``` sqlx::migrate!().run(&pool).await?; ``` 埋め込みはコンパイル時に行われるため、`migrations/`にファイルを足しただけでは再ビルドされないことがあります。`sqlx migrate build-script`を実行すると、変更を検知する`build.rs`が生成されます。 ``` $ sqlx migrate build-script Created `build.rs`; be sure to check it into version control! // generated by `sqlx migrate build-script` fn main() { // trigger recompilation when a new migration is added println!("cargo:rerun-if-changed=migrations"); } ``` 使い分けの基準は、マイグレーションを誰がいつ流すかです。アプリ1つがDBを専有し、起動とスキーマ更新を一体で扱いたいなら`migrate!`が向きます。複数のインスタンスが同時に起動する構成や、デプロイ前にDBA・レビュー担当が適用を確認する運用では、CIやデプロイ手順の中で`sqlx migrate run`を明示的に実行する方が事故を追いやすくなります。 ## cargo sqlx prepareによるオフラインビルドの準備 `query!`・`query_as!`マクロは、ビルド時に実DBへ接続してSQLの構文・列の型・NULL可否を検証します。そのままではDBの無いCIやDockerビルドでコンパイルが通りません。`cargo sqlx prepare`は検証結果を`.sqlx`ディレクトリに保存し、DBなしのビルドを可能にします。 ### .sqlxに書き出される中身 ``` $ cargo sqlx prepare query data written to .sqlx in the current directory; please check this into version control ``` 検証用アプリには`query!`系の呼び出しが4か所ありましたが、生成されたファイルは3つでした。ファイル名はSQL文字列のハッシュで、同じSQLを2か所で使うと1ファイルにまとまります。`SELECT`のファイルの要部は次のとおりで、列の型（`Int8`・`Text`）、パラメータの型、`nullable`が記録されます。 ``` { "db_name": "PostgreSQL", "query": "SELECT id, name FROM users WHERE id = $1", "describe": { "columns": [ { "ordinal": 0, "name": "id", "type_info": "Int8" }, { "ordinal": 1, "name": "name", "type_info": "Text" } ], "parameters": { "Left": ["Int8"] }, "nullable": [false, false] }, "hash": "220beaa3eb440cac34825e073d8fe3cf285373fec79ef1919a9440a0e235988c" } ``` ワークスペースで複数のクレートがマクロを使うなら`cargo sqlx prepare --workspace`でルートに1つの`.sqlx`を作ります。テストコードやfeatureの裏にあるクエリは、通常のビルドに入らないため保存されません。`cargo sqlx prepare -- --all-targets --all-features`のように、`--`の後ろにcargoへの引数を渡して対象に含めます。 ### SQLX\_OFFLINEとDATABASE\_URLの優先順位 ビルド時のマクロは、`DATABASE_URL`があればDBに接続し、無ければ`.sqlx`を読みます。`DATABASE_URL`が`.sqlx`より優先されるため、`.env`が残ったCIではDBへ接続しにいって失敗します。`SQLX_OFFLINE=true`（または`1`）を設定すると、`DATABASE_URL`があっても`.sqlx`だけを読みます。`.sqlx`に無いクエリを`SQLX_OFFLINE=true`でビルドしたときのエラーは次のとおりで、`cargo build`は終了コード101で止まりました。 ``` error: `SQLX_OFFLINE=true` but there is no cached data for this query, run `cargo sqlx prepare` to update the query cache or unset `SQLX_OFFLINE` --> src/main.rs:29:16 ``` ### CIでの`prepare --check`によるキャッシュ検証 `--check`は`.sqlx`を書き換えずに、現在のクエリとスキーマに対して古くなっていないかを判定します。SQLを1か所変えてから実行すると、終了コード1で次のように失敗しました。逆に、コードから消したクエリのキャッシュが`.sqlx`に残っているだけなら、`warning: potentially unused queries found in .sqlx`の警告が出るだけで終了コードは0でした。 ``` $ cargo sqlx prepare --check error: prepare check failed: .sqlx is missing one or more queries; you should re-run sqlx prepare ``` CIでは、テスト用のDBを立ててマイグレーションを適用した後に`cargo sqlx prepare --check`を実行し、本番イメージのビルドは`SQLX_OFFLINE=true`で行う、という2段構えにすると「`prepare`のやり忘れ」をマージ前に止められます。この構成はAxumなどでWebバックエンドをコンテナ化するときに効きます（[Axum（アクサム）とは？Rust製Webフレームワークの使い方・テスト・Actix Web比較【axum 0.8.9】](/tech/details/7602/)）。 ## SQLxでクエリを書く：query!・query\_as!・トランザクション 次のコードはsqlx 0.9.0とPostgreSQL 18.6でビルド・実行し、`inserted id = 1`、`User { id: 1, name: "Alice" }`、`committed, last id = 3`と出力されたものです。ビルド前に、検証用DBへ`sqlx migrate run`でスキーマを適用するか、対応する`.sqlx`を用意します。実行時の`migrate!`だけでは、コンパイル時の`query!`系マクロの検証を満たせません。 ``` use sqlx::postgres::PgPoolOptions; use sqlx::{Postgres, Transaction}; #[derive(Debug)] struct User { id: i64, name: String, } async fn insert_in_tx(tx: &mut Transaction<'_, Postgres>, name: &str) -> Result { let rec = sqlx::query!("INSERT INTO users (name) VALUES ($1) RETURNING id", name) .fetch_one(&mut **tx) .await?; Ok(rec.id) } #[tokio::main] async fn main() -> Result<(), Box> { let url = std::env::var("DATABASE_URL")?; let pool = PgPoolOptions::new().max_connections(5).connect(&url).await?; sqlx::migrate!().run(&pool).await?; let rec = sqlx::query!("INSERT INTO users (name) VALUES ($1) RETURNING id", "Alice") .fetch_one(&pool) .await?; println!("inserted id = {}", rec.id); let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", rec.id) .fetch_one(&pool) .await?; println!("{:?}", user); let mut tx = pool.begin().await?; sqlx::query!("INSERT INTO users (name) VALUES ($1)", "Bob") .execute(&mut *tx) .await?; let id = insert_in_tx(&mut tx, "Carol").await?; tx.commit().await?; println!("committed, last id = {}", id); Ok(()) } ``` - PostgreSQLで挿入した行のIDを受け取るには`RETURNING`と`fetch_one`を使います。MySQLの`last_insert_id()`に当たるメソッドはPostgreSQLにはありません。 - `query_as!`の第1引数はマッピング先の型です。列名と構造体のフィールド名が一致している必要があります。 - トランザクションは、所有している`tx`なら`&mut *tx`、`&mut Transaction`として受け取った関数内では`&mut **tx`を実行対象に渡します。0.6系までの`&mut tx`はコンパイルできません。 マクロを使わない`sqlx::query("...")`の引数は、0.9.0から`impl SqlSafeStr`になり、通常の文字列は`&'static str`として渡す必要があります。`format!`で組み立てた`String`を渡すと、`error[E0277]: dynamic SQL strings should be audited for possible injections`でコンパイルが止まります（検証環境で確認）。文字列連結によるSQLインジェクションをレビューで見つけやすくするための変更です。動的な値にはバインドパラメータや`QueryBuilder::push_bind`を使います。動的SQL文字列を直接渡す必要がある場合は、SQLインジェクションが起きないことを確認したうえで`sqlx::AssertSqlSafe(sql)`で包みます。このラッパー自体は入力の検証やエスケープを行いません。 SQLiteでも同じAPIで書けます。ただし`SqliteConnectOptions`の既定は`create_if_missing: false`で、ファイルが無いと接続に失敗します。アプリ側でファイルを作らせるなら接続文字列を`sqlite://app.db?mode=rwc`にするか、`create_if_missing(true)`を指定します。テスト用なら`sqlite::memory:`が使えます。 ## SQLxとsqlx-cliの採用判断 SQLx本体が対応するDBかどうかと、CLIに任せる処理を分けて判断します。 - **SQL Serverを使うなら採用しない**：SQLxの対応はPostgreSQL・MySQL・MariaDB・SQLiteで、MSSQLドライバーは0.7.0で削除されました。 - **動的SQLが中心なら`prepare`は限定的**：`prepare`とオフラインモードが効くのは`query!`系マクロのコンパイル時検証だけです。検索条件を`QueryBuilder`で組み立てるクエリが大半なら`prepare`の対象は限られますが、CLIによるマイグレーション管理はそのまま使えます。`query!`系マクロを使わない構成では`.sqlx`の管理自体が不要です。 - **`revert`だけを本番の復旧手順にしない**：`revert`はdown側のSQLを流すだけで、up側で消したデータは戻りません（`migrate add --help`にも明記）。列の追加のような可逆な変更はdown SQLで戻し、列やテーブルの削除などデータを失う変更は、バックアップからの復元か、修正用の新しいマイグレーションを流す前進修正で復旧する手順を別に用意します。 既存システムのDB設計やマイグレーション計画から相談したい場合は、[データベース設計・移行支援](https://www.issoh.co.jp/service/system/database/)も参考にしてください。 ## よくある質問 ### sqlx-cliとSQLx本体はどう違いますか？ SQLx本体はアプリからSQLを実行するクレートで、sqlx-cliはDBの作成、マイグレーション、`.sqlx`の生成を行うコマンドです。`query!`マクロや`migrate!`マクロはクレート側の機能なので、CLIが無くても使えます。CLIが必要になるのは、マイグレーションファイルを作る・手動で適用する・オフラインビルド用に`prepare`するときです。 ### cargo install sqlx-cliが遅い・失敗するときは？ 既定では3種類のDBドライバーとnative-tlsをすべてビルドするため、検証環境で約4分かかりました。`--no-default-features --features rustls,postgres`のように使うDBへ絞ると短くなります。OpenSSLが見つからずに失敗する場合は`rustls`を選ぶか`openssl-vendored`を付けます。0.9.0はRust 1.94.0以上が必要なので、`rustup update`も確認してください。 ### sqlx migrate runがエラーで止まるのはなぜですか？ `was previously applied but has been modified`なら、適用済みファイルの中身が変わり、`_sqlx_migrations`のチェックサムと一致しなくなっています。`sqlx migrate info`で`(different checksum)`の付いた版を探し、ファイルを元に戻して変更は新しいマイグレーションに移します。開発DBなら`sqlx database reset -y`で作り直しても解消します。 ### Goのsqlx（jmoiron/sqlx）とRustのSQLxは同じものですか？ 別物です。Goの`jmoiron/sqlx`は標準の`database/sql`に構造体へのスキャンなどを足すライブラリで、CLI・マイグレーション・コンパイル時検証は持ちません。sqlx-cliはRustのSQLx専用です。 ### sqlx-cliはSQLiteでも使えますか？ 使えます。`DATABASE_URL=sqlite:app.db`として`sqlx database create`を実行するとファイルが作られ、以降の`migrate`や`prepare`はPostgreSQLと同じ手順です。sqlx-cliが作るSQLiteのDBは既定でWALモードになり、アプリ側で別の`journal_mode`を指定すると`database is locked`の原因になるとヘルプに注記があります。 ## 関連記事 - [Cargo（Rust）とは？インストールとcargo installの使い方・主要コマンド一覧](/tech/details/9572/) - [Rustのasync/await入門｜Futureとpollの仕組み、Tokioでの実行とよくあるエラー](/tech/details/8681/) - [Axum（アクサム）とは？Rust製Webフレームワークの使い方・テスト・Actix Web比較【axum 0.8.9】](/tech/details/7602/) - [Rustのスタックとヒープ｜値がヒープへ脱出する条件とスタックオーバーフローの防ぎ方](/tech/details/2814/) --- 出典: [SQLx CLI（sqlx-cli）の使い方｜sqlx migrateとcargo sqlx prepareを0.9.0で実行して解説]()（株式会社一創）