Spouštění parametrizovaných dotazů

Parametrizované dotazy umožňují uchovávat zástupné symboly v SQL a zadávat hodnoty za běhu. Rozšíření PostgreSQL tyto hodnoty sváže jako parametry dotazu; nevkádá hodnoty do textu SQL.

Tuto stránku použijte, pokud chcete spustit SQL zkopírovaný z nástrojů nebo kódu aplikace, které používají zástupné symboly, jako :nameje , $1nebo ?.

Podporované syntaxe zástupných symbolů

Editor dotazů rozpozná tyto styly zástupných symbolů mimo textové řetězce, komentáře, přetypování, řezy polí, bloky uzavřené pomocí dollar-quotingu a operátory PostgreSQL pro JSON.

Pojmenované zástupné symboly

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

Pojmenované zástupné symboly rozlišují malá a velká písmena. Opakované výskyty stejného názvu sdílejí jeden řádek mřížky.

Poziční zástupné symboly PostgreSQL

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

$N zástupné symboly mají v rámci příkazu, který je obsahuje, pevně danou pozici.

Zástupné symboly pro umístění značky Qmark

select id, email
from users
where active = ?;

? zástupné symboly fungují v pořadí zleva doprava. ? na libovolné hodnotové pozici slouží jako parametr, včetně za operátory porovnání (>=, <=, <>), ve větvích CASE a v LIMIT/OFFSET. Operátory JSONB v PostgreSQL ?, ?| a ?& a operátor cesty JSON @? jsou rozpoznávány jako operátory, nikoli jako parametry.

Important

V každém příkazu použijte jeden styl zástupného symbolu. Příkaz, který kombinuje :name s $N nebo $N s ?, je před spuštěním odmítnut.

Otevření a použití karty Parametry

  1. Otevřete nebo vytvořte .sql soubor a připojte ho k databázi.
  2. Spusťte příkaz Execute Query (PostgreSQL),spusťte aktuální příkaz (PostgreSQL) nebo spusťte vybraný rozsah SQL.
  3. Pokud SQL obsahuje zástupné symboly, otevře se na dolním panelu karta Parametry .
  4. Zadejte hodnotu pro každý řádek, v případě potřeby zvolte typ a vyberte Spustit dotaz.
  5. Po prvním spuštění upravte hodnoty a výběrem příkazu Spustit opakujte dotaz.

Karta zobrazuje jeden řádek pro každý jedinečný pojmenovaný zástupný symbol a jeden řádek pro každý poziční zástupný symbol. Každý řádek obsahuje název zástupného symbolu nebo index, pole pro zadání hodnoty, zaškrtávací políčko NULL, rozevírací seznam pro výběr typu a akce pro řádek, pokud jsou k dispozici.

Skripty obsahující více příkazů

Poznámka (květen 2026): dřívější verze tohoto článku nesprávně označovaly poziční indexy jako nezávislé na jednotlivých příkazech. Chování se nezměnilo; opraví se pouze dokumentace.

Poziční parametry ($N, ?) sdílejí jedno pole hodnot napříč spuštěným skriptem. $1 (nebo první ?) v libovolném příkazu vždy vytvoří vazbu na stejnou hodnotu jako $1 v jakémkoli jiném příkazu. Opakované používání stejného pozičního indexu napříč příkazy nedává nezávislé hodnoty. Pokud potřebujete různé hodnoty pro stejný index v různých příkazech, použijte místo toho pojmenované parametry (:name).

Pokud sdílená pojmenovaná hodnota není kompatibilní s jedním z příkazů, které ji používají, vrátí PostgreSQL chybu a mřížka zachová vaše hodnoty, abyste je mohli upravit a spustit znovu.

Hodnoty NULL

Pomocí zaškrtávacího políčka NULL vytvořte vazbu SQL NULL. Pokud je toto políčko zaškrtnuté, pole hodnoty se pro tento řádek ignoruje.

Pokud zadáte doslovný text NULL, když není zaškrtnuté políčko NULL, tabulka vás upozorní, že se hodnota naváže jako text NULL, nikoli jako SQL NULL.

Volba typů parametrů

Výchozí typ rozevíracího seznamu je auto, který umožňuje PostgreSQL odvodit typ parametru. Zvolte typ, pokud chcete ověření na straně klienta nebo jasnější vazbu:

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

Ověření je měkké. Upozornění neblokuje odeslání; PostgreSQL zůstává posledním validátorem v době provádění.

Generování plánu dotazu s parametry

Při vizualizaci plánu dotazu pro SQL, který obsahuje zástupné symboly, karta Parametry řídí vizualizér plánu dotazu místo vrácení řádků. Tlačítko pro spuštění má text Vizualizovat plán dotazu a po prvním spuštění má text Vizualizovat znovu. Zadejte hodnoty a vyberte tlačítko pro spuštění EXPLAIN a otevření vizualizéru plánu dotazu. Tato cesta nevrací výsledky dotazu.

Použijte možnost Ignorovat

Funkci Ignorovat použijte, když mřížka zobrazuje token, který by měl zůstat v SQL, například platný operátor PostgreSQL. Ignorování je povoleno pouze v případech, kdy token zůstane platným SQL bez vazby.

Úprava SQL a opětovné spuštění

Když otevřete kartu Parametry , můžete upravit SQL a vybrat Spustit znovu. Rozšíření znovu extrahuje zástupné symboly a porovná nový šablonovaný SQL s předchozím otiskem prstu.

Pokud se sada zástupných symbolů změnila, upozornění na změny shrnuje, co se změnilo, například které zástupné symboly byly přidány nebo odebrány. Rozšíření sloučí hodnoty dopředu, pokud zástupný symbol stále odpovídá názvu nebo pozičnímu indexu. Pokud se odeberou všechny zástupné symboly, mřížka se zavře a dotaz se normálně spustí.

Zrušení a obnovení transakcí

Zatímco je parametrizované spuštění aktivní, tlačítko spuštění se změní na ovládací prvek zastavení (označený jako Storno). Zrušení přeruší dávku v letu, přeskočí pozdější dávky a ponechá kartu Parametry otevřenou s hodnotami beze změny. Zrušené spuštění místo selhání zobrazuje zrušený stav dávky, takže jeho řádky nejsou zvýrazněné jako chyby.

Rozšíření automaticky nevrací transakce spuštěné uživatelem. Pokud zrušení ponechá připojení ve stavu přerušené transakce, na kartě Parametry se zobrazí oznámení o zotavení s možností Spustit ROLLBACK. Vyberte tuto možnost, chcete-li v rámci stejného připojení vydat jeden explicitní ROLLBACK, a potom skript spusťte znovu.

Zkontrolovat selhání a opakovat akci

Když parametrizované spuštění selže, karta Parametry uchovává hodnoty a zobrazuje stav selhání se souhrnem chyb databáze. Výběrem možnosti Zobrazit zprávy otevřete úplné podrobnosti zprávy.

Zrušená spuštění zobrazují zrušený stav odděleně od neúspěšných spuštění a novější dávky, které se nespustí, se označí jako přeskočené.

Po opravě hodnoty nebo typu vyberte Spustit znovu. Karta vymaže zastaralou chybu, zrušení a stav zvýraznění řádku pro nový pokus. Pokud je připojení stále v přerušené transakci, zobrazí se oznámení o obnovení znovu.

Uchovávání hodnot historie dotazů

Nastavení pgsql.queryPlaceholders.historyValueRetention určuje, jestli se hodnoty parametrů zachovají v historii dotazů v paměti aktuální relace:

Value Behavior
ask Po každém úspěšném parametrizovaném spuštění se zeptejte.
always Zachovejte hodnoty položek historie relace bez dotazu.
never Zachovat pouze šablonované SQL.

Když je ask aktivní, po úspěšném spuštění se zobrazí výzva, která nabízí možnosti Uložit jednou (ponechat pouze tuto položku), Vždy uložit (také přepne nastavení na always), Přeskočit (pouze pro šablonované SQL) a Neptat se znovu (také přepne nastavení na never).

Hodnoty se uchovávají pouze v paměti a jsou vymazány, když se VS Code znovu načte nebo se pracovní prostor změní. Hodnoty parametrů jsou redactovány z telemetrie a protokolů.

PŘIPRAVIT upozornění

PREPARE ... AS SELECT $1 používá syntaxi pozice na straně serveru PostgreSQL. Rozšíření detekuje příkazy PREPARE a ponechává zástupné symboly v těle PREPARE pro PostgreSQL namísto jejich navázání na straně klienta. Ostatní příkazy ve stejném skriptu se analyzují normálně.

Nepodporované případy MVP

MVP nezahrnuje:

  • Perzistentní historie hodnot ukládaná na disk.
  • Pojmenované nebo uložené sady parametrů napříč relacemi editoru
  • Opakované použití na straně PREPARE/EXECUTE serveru jako parametrizované spouštění na straně klienta
  • Složené, pole, bajty, rozsah, interval, výčt nebo jiná vazba typu nad rámec podporovaných typů rozevíracích seznamů.

Související obsah

  • Last updated on