パラメーター化されたクエリを実行する

パラメーター化されたクエリを使用すると、SQL にプレースホルダーを保持し、実行時に値を指定できます。 PostgreSQL 拡張機能は、これらの値をクエリ パラメーターとしてバインドします。SQL テキストに値が貼り付けられません。

このページは、 :name、 $1、 ?などのプレースホルダーを使用するツールまたはアプリケーション コードからコピーされた SQL を実行する場合に使用します。

サポートされているプレースホルダー構文

クエリ エディターは、文字列、コメント、キャスト、配列スライス、ドル引用符で囲まれた本文、PostgreSQL JSON 演算子の外部でこれらのプレースホルダー スタイルを検出します。

名前付きプレースホルダー

select id, email
from users
where id = :user_id;

名前付きプレースホルダーでは、大文字と小文字が区別されます。 同じ名前が繰り返し出現すると、1 つのグリッド行が共有されます。

PostgreSQL の位置指定プレースホルダー

select id, email
from users
where id = $1;

$N プレースホルダーは、それを含む文の中で位置によって決まります。

Qmark の位置指定プレースホルダー

select id, email
from users
where active = ?;

? プレースホルダーは左から右の順序で動作します。 任意の値位置の ? は、比較後演算子 (>=、 <=、 <>)、 CASE 分岐、および LIMIT/OFFSETを含むパラメーターとして機能します。 PostgreSQL の JSONB 演算子 ?、 ?|、および ?& と JSON パス演算子 @? は、パラメーターではなく演算子として認識されます。

[パラメーター] タブを開いて使用する

1. .sql ファイルを開くか作成し、データベースに接続します。
2. クエリ実行 (PostgreSQL)、現在のステートメントの実行 (PostgreSQL)、または選択した SQL 範囲を実行します。
3. SQL にプレースホルダーが含まれている場合は、下部のパネルに [パラメーター] タブが開きます。
4. 各行の値を入力し、必要に応じて種類を選択し、[ クエリの実行] を選択します。
5. 最初の実行後、値を編集し、[ 実行] をもう一度 選択してクエリを繰り返します。

タブには、一意の名前付きプレースホルダーごとに 1 行、位置指定プレースホルダーごとに 1 行が表示されます。 各行には、プレースホルダー名またはインデックス、値入力、 NULL チェック ボックス、型ドロップダウン リスト、および使用可能な場合の行アクションが含まれます。

複数ステートメント スクリプト

注 (2026 年 5 月): この記事の以前のバージョンでは、位置指定インデックスがステートメントに依存しないものとして誤って説明されています。 動作は変更されませんでした。ドキュメントのみが修正されます。

位置指定パラメーター ($N、 ?) は、実行されたスクリプト全体で 1 つの値配列を共有します。 $1 (または最初の ?)任意のステートメントでは、常に他のステートメントの $1 と同じ値にバインドされます。 ステートメント間で同じ位置指定インデックスを再利用しても、独立した値は得られません。 異なるステートメントで同じインデックスに異なる値が必要な場合は、代わりに名前付きパラメーター (:name) を使用します。

共有された名前付き値とそれを使用するステートメントの 1 つと互換性がない場合、PostgreSQL はエラーを返し、グリッドは値を保持して、再調整して実行できるようにします。

NULL 値

SQL をバインドするには、NULL チェック ボックスを使用します。 チェックされている場合、その行の値フィールドは無視されます。

NULL チェック ボックスがオフの状態でリテラル テキストを入力すると、SQL NULLではなく、値がテキスト NULLとしてバインドされるとグリッドから警告が表示されます。

パラメーターの種類を選択する

型ドロップダウン リストの既定値は auto であり、PostgreSQL はパラメーターの型を推論できます。 クライアント側の検証またはより明確なバインドが必要な場合は、型を選択します。

• text
• integer
• bigint
• numeric
• boolean
• date
• timestamp
• timestamptz
• uuid
• json
• jsonb

検証は緩やかです。 警告は送信をブロックしません。PostgreSQL は、実行時に最終的な検証コントロールのままです。

パラメーターを使用してクエリ プランを生成する

プレースホルダーを含む SQL のクエリ プランを視覚化すると、[パラメーター] タブによって、行が返されるのではなく、クエリ プラン ビジュアライザーが駆動されます。 実行ボタンには クエリ プランの視覚化 と表示され、初回の実行後は 再度視覚化 と表示されます。 値を入力し、ボタンを選択して EXPLAIN 実行し、 クエリ プラン ビジュアライザーを開きます。 このパスはクエリ結果を返しません。

無視を使用する

有効な PostgreSQL 演算子など、SQL に残る必要があるトークンがグリッドに表示されている場合は 、[無視] を使用します。 無視は、トークンがバインドなしで有効な SQL のままである場合にのみ有効になります。

SQL を編集してもう一度実行する

[パラメーター] タブを開くと、SQL を編集し、[再実行] を選択できます。 この拡張機能はプレースホルダーを再抽出し、新しいテンプレート化された SQL と以前のフィンガープリントを比較します。

プレースホルダー セットが変更された場合、プレースホルダーの追加や削除など、変更された内容がドリフト バナーに要約されます。 この拡張機能は、プレースホルダーが名前または位置インデックスで引き続き一致している場合、値を後続へマージします。 すべてのプレースホルダーが削除されると、グリッドが閉じられ、クエリが正常に実行されます。

トランザクションの取り消しと復旧

パラメーター化された実行がアクティブな間は、実行ボタンが 停止 コントロール ( "キャンセル" というラベル) に変わります。 キャンセルは、実行中のバッチを中断し、後のバッチをスキップし、[ パラメーター] タブを開いたままにして値をそのままにします。 取り消された実行では、 失敗ではなく取り消された バッチの状態が表示されるため、その行はエラーとして強調表示されません。

拡張機能では、ユーザーが開始したトランザクションは自動ロールバックされません。 取り消しによって接続が中止されたトランザクション状態のままになる場合、パラメーター タブには、Execute ROLLBACK を含む回復通知が表示されます。 これを選択して、同じ接続に対して 1 つの明示的な ROLLBACK を発行し、スクリプトをもう一度実行します。

エラーを確認して再試行する

パラメーター化された実行が失敗した場合、[ パラメーター] タブには値が保持され、失敗した状態がデータベース エラーの概要と共に表示されます。 [ メッセージの表示] を選択して、メッセージの詳細全体を開きます。

取り消された実行では、失敗した実行とは別に取り消された状態が表示され、実行されなかった後のバッチはスキップ済みとしてマークされます。

値または種類を修正したら、[再実行] を選択 します。 タブは、新しい試行の古いエラー、取り消し、行強調表示の状態をクリアします。 接続がまだ中止されたトランザクション内にある場合は、復旧通知が再び表示されます。

クエリ履歴値の保持

pgsql.queryPlaceholders.historyValueRetention設定では、パラメーター値を現在のセッションのメモリ内クエリ履歴に保持するかどうかを制御します。

askがアクティブな場合、正常に実行された後に表示されるプロンプトは、1 回保存 (このエントリのみを保持)、常に保存 (設定をalwaysに切り替える)、スキップ (テンプレート化された SQL のみ)、もう一度要求しない (設定をneverに切り替える) ことを示します。

値はメモリ内にのみ保持され、VS Code の再読み込みまたはワークスペースの変更時にクリアされます。 パラメーター値は、テレメトリとログから編集されます。

PREPARE に関する注意事項

PREPARE ... AS SELECT $1 では、PostgreSQL サーバー側の位置指定構文が使用されます。 拡張機能は PREPARE ステートメントを検出し、プレースホルダーをクライアント上でバインドするのではなく、PostgreSQL の PREPARE 本文内に残します。 同じスクリプト内の他のステートメントは、通常どおりに解析されます。

サポートされていない MVP ケース

MVP には以下は含まれません。

• ディスクに保存される永続的な値の履歴。
• エディター セッション間で名前付きまたは保存されたパラメーター セット。
• サーバー側 PREPARE/EXECUTE クライアント側のパラメーター化された実行として再利用されます。
• サポートされているドロップダウン リスト型以外の複合、配列、バイト、範囲、間隔、列挙型、またはその他の型バインド。

関連するコンテンツ

• クエリ エディターと IntelliSense
• クエリ プラン ビジュアライザー
• クイック スタート: PostgreSQL に接続してクエリを実行する
• 設定リファレンス