執行參數化查詢

參數化查詢可以在 SQL 中保留佔位符，並在執行時提供值。 PostgreSQL 擴充功能將這些值綁定為查詢參數;它不會把數值貼到 SQL 文字裡。

當你想執行從使用佔位符（如 :name、 $1、 或 ?）的工具或應用程式代碼複製的 SQL 時，請使用此頁面。

支援的佔位語法

查詢編輯器會偵測這些預留位置樣式，除了字串、註解、投放、陣列切片、美元引號主體以及 PostgreSQL JSON 運算子之外。

命名的預留位置

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

命名佔位符是區分大小寫的。 同一名稱重複出現時，會共用同一個網格列。

PostgreSQL 位置預留位置

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

$N 佔位符在包含它們的語句中具有固定位置。

Qmark 位置佔位符

select id, email
from users
where active = ?;

? 佔位符會依照由左至右的順序運作。 位於任何值位置的 A ? 都會作為參數，包括在比較運算子（>=、<=、<>）之後、在 CASE 分支中，以及在 LIMIT/OFFSET 中。 PostgreSQL 的 JSONB 運算子 ?、、 ?|以及 ?& JSON 路徑運算子 @? 被視為運算子，而非參數。

Important

每個陳述式僅使用一種預留位置樣式。 混用 :name 與 $N，或混用 $N 與 ? 的陳述式，會在執行前被拒絕。

打開並使用參數標籤

  1. 打開或建立一個 .sql 檔案，然後連接到資料庫。
  2. 執行執行查詢（PostgreSQL）、執行目前陳述式（PostgreSQL），或執行選取的 SQL 範圍。
  3. 如果 SQL 包含佔位符，底部面板會開啟 參數 標籤。
  4. 為每列輸入一個值，若需要選擇類型，然後選擇 執行查詢。
  5. 第一次執行後，編輯數值並 再次選擇執行 以重複查詢。

索引標籤會顯示每個唯一命名預留位置的一個列，以及每個位置預留位置的一個列。 每一列都包含預留位置名稱或索引、值輸入欄位、NULL 核取方塊、類型下拉式清單，以及列動作（如有提供）。

多陳述式指令碼

註（2026年5月）： 本文早期版本錯誤地將位置索引描述為逐語句獨立。 行為沒有改變;只有文件被更正。

位置參數（$N， ?）在執行的腳本中共用一個值陣列。 $1（或第一個 ?）在任何陳述式中，總是會繫結至與任何其他陳述式中的 $1 相同的值。 在不同語句間重複使用相同的位置索引，並不會讓它們獲得獨立的值。 如果你需要不同語句中同一索引的不同值，請改用命名參數（:name）。

如果共用的命名值與使用該值的語句不相容，PostgreSQL 會回傳錯誤，網格會保留你的值，讓你可以調整並重新執行。

NULL 值

使用 NULL 勾選框來綁定 SQL NULL。 當勾選時，該欄位的值欄位會被忽略。

如果你在 NULL 核取方塊未勾選時輸入原樣文字 NULL，方格會警告你，該值會繫結為文字 NULL，而不是 SQL NULL。

選擇參數類型

類型下拉選單預設為 auto，讓 PostgreSQL 可以推斷參數類型。 當你想要用戶端驗證或更明確的繫結時，請選擇類型：

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

驗證是寬鬆的。 警告不會阻止提交；PostgreSQL 在執行時仍是最終驗證者。

產生帶有參數的查詢計畫

當你視覺化包含佔位符的 SQL 查詢計畫時，參數標籤會驅動查詢計畫視覺化工具，而不是回傳列。 執行按鈕顯示 「可視化查詢計畫」，第一次執行後又會顯示 「可視化」。 輸入數值，選擇執行 EXPLAIN 按鈕，然後開啟 查詢計畫視覺化工具。 此路徑不會回傳查詢結果。

使用「忽略」

當格線顯示某個應留在 SQL 中的詞元時，請使用 忽略，例如有效的 PostgreSQL 運算子。 忽略功能僅在憑證仍為有效且未綁定時啟用。

編輯 SQL 然後再執行一次

當你打開 參數 標籤時，可以編輯 SQL 並 再次選擇執行。 擴充功能會重新擷取預留位置，並將新的套用範本的 SQL 與先前的指紋進行比較。

如果佔位符集有變動，漂移橫幅會總結變更內容，例如新增或移除佔位符。 當預留位置依名稱或位置索引仍然相符時，擴充功能會將值向前合併。 如果所有佔位符都被移除，網格會關閉，查詢會正常執行。

取消與恢復交易

當參數化的運行啟動時，執行按鈕會切換為 停止 控制（標記為 取消）。 取消會中斷正在執行中的批次、跳過後續批次，並讓 參數 索引標籤維持開啟，且其中的值保持不變。 取消的執行會顯示 取消 批次狀態，而非失敗，因此其列不會被標示為錯誤。

此擴充功能不會自動回復由使用者啟動的交易。 若取消使連線處於中止交易狀態，參數標籤會顯示恢復通知，並執行 ROLLBACK。 選擇它在同一連線上發出一個明確的指令 ROLLBACK ，然後再執行腳本。

檢視失敗項目並重試

當參數化執行失敗時， 參數 分頁會保留你的數值，並顯示失敗狀態及資料庫錯誤摘要。 選擇 「查看訊息 」以開啟完整訊息詳情。

被取消的批次會與失敗的執行分開顯示取消狀態，而未執行的後續批次則被標記為跳過。

固定值或類型後，再次選擇 執行。 索引標籤會為新的嘗試清除舊有的失敗、取消和資料列醒目提示狀態。 如果連線仍在中止交易中，恢復通知會再次出現。

查詢歷史值保留

此設定 pgsql.queryPlaceholders.historyValueRetention 控制參數值是否保留在當前會話的記憶體內查詢歷史中：

價值 行為
ask 每次成功的參數化執行後都要詢問。
always 保留工作階段中歷史紀錄的值，無需提示。
never 只保留範本 SQL。

當 啟用時 ask ，成功執行後顯示的提示包括 ：只存檔一次 （只保留此條目）、 永遠儲存 （同時切換設定為 always）、 跳過 （僅限模板化 SQL）以及 「不要再問 」（也請將設定改為 never）。

這些值僅儲存在記憶體中，當 VS Code 重新載入或工作區變更時會被清除。 參數值會從遙測和日誌中被遮蔽。

準備附帶警告

PREPARE ... AS SELECT $1 使用 PostgreSQL 伺服器端位置語法。 擴充功能會偵測到PREPARE陳述式，並在PREPARE主體內保留 PostgreSQL 的佔位符，而不是在用戶端上繫結它們。 相同程式碼的其他陳述句則正常剖析。

不支援的 MVP 案例

MVP 不包括：

  • 永續性磁碟支援的的值歷史。
  • 跨編輯器工作階段的已命名或已儲存參數集。
  • 伺服器端PREPARE/EXECUTE重用作為用戶端參數化執行。
  • 複合資料、陣列、bytea、範圍、間隔、列舉或其他超出支援之下拉式清單類型的類型繫結。

相關內容

  • Last updated on