SQLパラメータバインディングの置換ルールを確認

?、:id、@name のようなプレースホルダを含むSQLに、実際の値がどのように代入されて完成クエリになるかは、4つのルールさえ知っていれば目で追えます。数値と null・true・false は引用符なしでそのまま、文字列はシングルクォートで囲み、引用符内の文字とコメントには手を付けない——これがポイントです。
この記事では、そのルールを手作業で適用する方法と、結果をすぐに目で確認する方法を整理します。ログに残った ? クエリを再現したい開発者や、ドライバが値をどのように埋めるのか知りたい人に必要な内容です。
要点 ① 順序方式(
?、$1)は値の順番どおりに、名前付き方式(:name、@name、$name)は同じ名前どうしで、JSONは配列なら順番、オブジェクトなら名前で埋めます。 ② 数値とnull・true・falseは引用符なしで、それ以外の文字列はシングルクォートで囲み、PostgreSQLでは'を''に、MySQL・SQLiteでは\'にエスケープします。 ③ 文字列定数'...'やコメント(--、/* */)の中にある?・:nameは本物のプレースホルダではないので、そのままにします。
なぜ値が期待と違う形で埋められるのか
アプリケーションのログやORMのデバッグ出力には、値が埋められる前のクエリがそのまま記録されることがよくあります。WHERE id = ? や WHERE id = :id の状態です。
問題を再現するには、その場所に実際の値が入った完成クエリが必要ですが、値を手作業で当てはめるとミスが起きます。文字列の引用符を忘れたり、名前が合っていないのに値が埋まったと勘違いしたりするものです。
特に2つの状況で結果が想定とずれます。名前付き方式で書いたのにクエリに ? が混ざっていると、その ? は埋められません。順序方式なのに値の個数がプレースホルダの数と違うと、余る場所や足りない場所が生じます。なぜそうなるかは、ルールを見ればはっきりします。
ツールを使わずに手作業で値を代入するルール
バインディングは2つの段階です。どこが本当のプレースホルダなのかを見つけ、その場所に値を形式に合わせて書き込むという流れです。ルールを順番に適用すれば、手作業でも完成クエリを作れます。
ステップ1 — プレースホルダの方式を決めます。 3つの方式では、値の対応付けの方法が異なります。
- 順序方式:
?と$1、$2… を値の順番どおりに埋めます。$1は1番目の値、$2は2番目の値です。 - 名前付き方式:
:name、@name、$nameを同じ名前の値と対応させます。順番は関係ありません。 - JSON: 配列
[...]を渡すと順序方式のように、オブジェクト{...}を渡すと名前付き方式のように動作します。
ステップ2 — 値を形式に合わせて書きます。 値の「見た目」によって、引用符を付けるかどうかが変わります。
- 純粋な数値(
25、-3、25.5)は引用符なしでそのまま書きます。 null、true、false(大文字・小文字は問いません)は、それぞれNULL、TRUE、FALSEというキーワードで書きます。- それ以外の値はすべて文字列とみなし、シングルクォートで囲みます。
ステップ3 — 文字列内の引用符をエスケープします。 値の中にシングルクォートがある場合、DBごとに処理が異なります。
- PostgreSQL:
'を''(シングルクォート2つ)に置き換えます。O'Brien→'O''Brien' - MySQL・MariaDB・SQLite:
'を\'に、バックスラッシュ\は\\に置き換えます。O'Brien→'O\'Brien'
ステップ4 — 文字列定数とコメントには手を付けません。 手作業で最も間違えやすい部分です。
クエリ内にすでに '?' のように引用符で囲まれた疑問符がある場合や、-- メモ ? のようにコメント内に疑問符がある場合、それはプレースホルダではありません。'...' の中、-- の後の1行、/* */ の間は、すべて原文のままにします。
たとえば SELECT '?' AS mark FROM t WHERE id = ? に順序方式の値 5 を渡すと、前の '?' はそのままにして、後ろの ? だけを 5 で埋めます。結果は SELECT '?' AS mark FROM t WHERE id = 5 になります。
Dynamic Labsの無料ツール「SQL パラメータバインディング確認ツール」で確認してみましょう。
インストールやログインなしで、ブラウザからすぐに実行できます。MySQL・PostgreSQL・SQLite のエスケープ規則に対応し、順序型・変数名・JSON 入力を扱えます。

よくある誤解と結果の読み方
値の見た目によって結果がどのように表記されるかを、まず整理すると次のとおりです。
| 入力した値 | 結果の表記 | 理由 |
|---|---|---|
| 25 | 25 | 純粋な数値は引用符なし |
| null / TRUE / false | NULL / TRUE / FALSE | キーワードとして認識(大文字・小文字は問わない) |
| administrator | 'administrator' | 文字列はシングルクォートで囲む |
| O'Brien (PostgreSQL) | 'O''Brien' | ' を '' にエスケープ |
| O'Brien (MySQL・SQLite) | 'O'Brien' | ' を \' にエスケープ |
名前付き方式なのに ? がそのまま残る場合。 名前付き方式では、名前だけを頼りに値を探します。? には名前がないため埋める対象にならず、そのまま ? として残ります。上の画面の基本的な例がまさにこの状況です — :min_age と @user_role には値が入りましたが、? はそのままです。順序方式の位置と名前付き方式の位置を1つのクエリに混在させた場合は、方式を1つに統一する必要があります。
名前が一致しない場合。 名前付き方式で、クエリの :user_id と値の userId のように綴りが違うと、対応付けできず :user_id がそのまま残ります。埋められていない名前が結果に表示されたら、タイプミスを疑うとよいでしょう。
順序方式なのに値の個数が合わない場合。 プレースホルダより値が少ないと、足りない位置は NULL で埋められ、値が多いと余った値は無視されます。たとえば VALUES (?, ?, ?) に値が2つ(1、hello)だけだと、VALUES (1, 'hello', NULL) になります。
文字列の 'null' を入れたい場合。 値の見た目で判断するため、null と書くと文字列ではなく NULL キーワードになります。007 のように先頭に0があっても、純粋な数値の形式なら引用符なしで 007 と出力されます。意図と違う結果になることがあるので、結果を目で確認するのが安全です。
最後に、誤解してはいけないことがあります。このツールが引用符をエスケープするからといって、SQLインジェクションが防げるわけではありません。これは完成クエリを目で確認するための組み立てシミュレーターであり、実際のサーバーコードでは値を文字列として連結せず、PreparedStatement やドライバのネイティブバインディングを使う必要があります。
まとめ
- 3つの方式では、値を埋める基準が異なります。順序方式は順番、名前付き方式は名前、JSONは配列なら順番、オブジェクトなら名前です。
- 値の見た目が引用符を決めます。純粋な数値と
null・true・falseはそのまま、それ以外はシングルクォートで囲みます。 - 引用符のエスケープはDBごとに異なります。PostgreSQLは
''、MySQL・SQLiteは\'です。 - 文字列定数とコメント内の
?・:nameはプレースホルダではないため、そのまま残ります。 - このツールは結果を確認するための組み立てシミュレーターです。実際のサーバーコードでは、PreparedStatement やネイティブのパラメータバインディングを使うのが標準です。
インストールやログインなしで、ブラウザからすぐに実行できます。MySQL・PostgreSQL・SQLite のエスケープ規則に対応し、順序型・変数名・JSON 入力を扱えます。
よくある質問
文字列やコメントの中にある ? も値に置き換わりますか?
いいえ。シングルクォートで囲んだ文字列定数 '...'、1行コメント --、ブロックコメント /* */ の中にある ? や :name は本当のプレースホルダではないため、そのまま残します。ツールはクエリを1文字ずつ走査しながら、現在の位置が文字列やコメントの中かどうかを判断するので、クエリが壊れることはありません。
変数名モードにしたのに ? が置き換わらず残るのはなぜですか?
正常な動作です。変数名モードは、名前(:name、@name、$name)が一致する値だけを埋めます。? は名前がないため埋める対象ではなく、そのまま残ります。? を埋めたい場合は順序型モードに切り替えるか、クエリ内のプレースホルダを1つの方式に統一してください。
順序型で値の個数がプレースホルダより少ない場合はどうなりますか?
足りない部分は NULL で埋められ、値が多い場合は余った値が無視されます。結果のクエリに想定外の NULL が見えたら、値の行数と ?・$n の個数が合っているか確認してください。
このツールで作成したクエリをそのまま実行してもよいですか?
学習・再現・デバッグ用途の組み合わせシミュレーターと捉えるのが適切です。実際のアプリケーションでは、値を直接連結する代わりに、PreparedStatement やドライバーのネイティブバインディングを使うのが標準的な方法です。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む