Exécuter des requêtes paramétrables

Les requêtes paramétrables vous permettent de conserver des espaces réservés dans SQL et de fournir des valeurs au moment de l’exécution. L’extension PostgreSQL lie ces valeurs en tant que paramètres de requête ; il ne colle pas les valeurs dans le texte SQL.

Utilisez cette page lorsque vous souhaitez exécuter SQL copié à partir d’outils ou de code d’application qui utilisent des espaces réservés tels que :name, $1ou ?.

Syntaxes de paramètres de substitution prises en charge

L'éditeur de requêtes détecte ces styles d'espace réservé en dehors des chaînes, des commentaires, des casts, des tranches de tableau, des corps entre guillemets dollar et des opérateurs JSON PostgreSQL.

Espaces réservés avec nom

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

Les espaces réservés nommés sont sensibles à la casse. Les occurrences répétées du même nom partagent une ligne de grille.

Paramètres positionnels PostgreSQL

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

$N les marqueurs de substitution sont positionnés en fonction de leur place dans l’énoncé qui les contient.

Espaces réservés positionnels Qmark

select id, email
from users
where active = ?;

Les espaces réservés ? fonctionnent dans l'ordre de gauche à droite. Dans toute position de valeur, ? est considéré comme un paramètre, y compris après les opérateurs de comparaison (>=, <=, <>), dans les branches CASE et dans LIMIT/OFFSET. Les opérateurs JSONB ?, ?| et ?& de PostgreSQL, ainsi que l’opérateur de chemin JSON @?, sont reconnus comme des opérateurs, et non comme des paramètres.

Important

Utilisez un seul style d'espace réservé dans chaque instruction. Une instruction qui mélange :name avec $N, ou $N mélange avec ?, est rejetée avant l’exécution.

Ouvrir et utiliser l’onglet Paramètres

  1. Ouvrez ou créez un .sql fichier et connectez-le à une base de données.
  2. Exécutez la requête d’exécution (PostgreSQL),l’instruction actuelle (PostgreSQL) ou exécutez une plage SQL sélectionnée.
  3. Si le code SQL contient des espaces réservés, l’onglet Paramètres s’ouvre dans le volet inférieur.
  4. Entrez une valeur pour chaque ligne, choisissez un type si nécessaire, puis sélectionnez Exécuter la requête.
  5. Après la première exécution, modifiez les valeurs et sélectionnez Réexécuter la requête.

L’onglet affiche une ligne pour chaque espace réservé nommé unique et une ligne pour chaque espace réservé positionnel. Chaque ligne comprend le nom ou l’index de l’espace réservé, un champ de saisie de valeur, une case à cocher NULL, une liste déroulante de type et des actions de ligne lorsqu’elles sont disponibles.

Scripts à plusieurs instructions

Remarque (mai 2026) : les versions antérieures de cet article décrivaient à tort les index positionnels comme étant indépendants pour chaque instruction. Le comportement n’a pas changé ; seule la documentation est corrigée.

Les paramètres positionnels ($N, ?) partagent un tableau de valeurs unique sur le script exécuté. $1 (ou le premier ?) dans n’importe quelle instruction se lie toujours à la même valeur que $1 dans toute autre instruction. La réutilisation du même index positionnel entre les instructions ne leur donne pas de valeurs indépendantes. Si vous avez besoin de valeurs différentes pour le même index dans différentes instructions, utilisez des paramètres nommés (:name) à la place.

Si une valeur nommée partagée n’est pas compatible avec l’une des instructions qui l’utilisent, PostgreSQL retourne l’erreur et la grille conserve vos valeurs afin que vous puissiez ajuster et réexécuter.

Valeurs nulles

Utilisez la case à cocher NULL pour lier la valeur SQL NULL. Lorsqu’elle est cochée, le champ valeur est ignoré pour cette ligne.

Si vous saisissez le texte littéral NULL alors que la case à cocher NULL est désactivée, la grille vous avertit que la valeur est interprétée comme le texte NULL, et non comme SQL NULL.

Choisir des types de paramètres

La liste déroulante de type est autopar défaut , ce qui permet à PostgreSQL de déduire le type de paramètre. Choisissez un type lorsque vous souhaitez une validation côté client ou une liaison plus claire :

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

La validation est souple. Un avertissement ne bloque pas la soumission ; PostgreSQL reste le validateur final au moment de l’exécution.

Générer un plan de requête avec des paramètres

Lorsque vous visualisez un plan de requête pour SQL qui contient des espaces réservés, l’onglet Paramètres pilote le visualiseur du plan de requête au lieu de retourner des lignes. Le bouton Exécuter affiche Visualiser le plan de requête et, après la première exécution, affiche Visualiser à nouveau. Entrez des valeurs et sélectionnez le bouton à exécuter EXPLAIN et ouvrez le visualiseur du plan de requête. Ce chemin d’accès ne retourne pas les résultats de la requête.

Utiliser l’option Ignorer

Utilisez Ignorer quand la grille affiche un jeton qui doit rester dans SQL, tel qu’un opérateur PostgreSQL valide. L'option Ignorer n'est activée que lorsque le jeton reste valide SQL sans liaison.

Modifier SQL et réexécuter

Lorsque vous ouvrez l’onglet Paramètres , vous pouvez modifier le code SQL et sélectionner Réexécuter. L'extension réextrait les espaces réservés et compare le nouveau SQL basé sur modèle à l'empreinte précédente.

Si l'ensemble d'espaces réservés a changé, une bannière flottante résume les modifications, telles que les espaces réservés ajoutés ou supprimés. L'extension fusionne les valeurs lorsque l'espace réservé correspond encore par nom ou par index positionnel. Si tous les espaces réservés sont supprimés, la grille se ferme et la requête s’exécute normalement.

Annuler et récupérer des transactions

Pendant qu’une exécution paramétrable est active, le bouton d’exécution passe à un contrôle d’arrêt (étiqueté Annuler). Annuler interrompt le lot en cours, ignore les lots ultérieurs et laisse l’onglet Paramètres ouvert avec des valeurs intactes. Une exécution annulée affiche l’état du lot annulé plutôt qu’un échec, de sorte que ses lignes ne sont pas mises en surbrillance en tant qu’erreurs.

L’extension ne restaure pas automatiquement les transactions démarrées par l’utilisateur. Si l’annulation laisse la connexion dans un état de transaction abandonné, l’onglet Paramètres affiche une notification de récupération avec Execute ROLLBACK. Sélectionnez-le pour émettre un explicite ROLLBACK sur la même connexion, puis réexécutez le script.

Examiner les échecs et réessayer

Lorsqu’une exécution paramétrable échoue, l’onglet Paramètres conserve vos valeurs et affiche l’état ayant échoué avec le résumé des erreurs de base de données. Sélectionnez Afficher les messages pour ouvrir les détails complets du message.

Les exécutions annulées affichent un état d'annulation distinct de celui des exécutions avec échec, et les lots ultérieurs qui n'ont pas été exécutés sont marqués comme ignorés.

Après avoir corrigé une valeur ou un type, sélectionnez Réexécuter. L'onglet réinitialise les anciens états d'échec, d'annulation et de mise en surbrillance des lignes avant une nouvelle tentative. Si la connexion est toujours dans une transaction abandonnée, l’avis de récupération s’affiche à nouveau.

Rétention des valeurs de l’historique des requêtes

Le paramètre pgsql.queryPlaceholders.historyValueRetention contrôle si les valeurs des paramètres sont conservées dans l’historique des requêtes en mémoire de la session actuelle :

Valeur Behavior
ask Demandez après chaque exécution paramétrable réussie.
always Conserver les valeurs des entrées d'historique de session sans invite.
never Conservez uniquement le SQL paramétré.

Lorsque ask est activé, l’invite affichée après une exécution réussie propose Enregistrer une fois (conserve uniquement cette entrée), Toujours enregistrer (et bascule aussi le paramètre sur always), Ignorer (SQL paramétré uniquement) et Ne plus demander (et bascule aussi le paramètre sur never).

Les valeurs sont conservées en mémoire uniquement et sont effacées lorsque VS Code recharge ou que l’espace de travail change. Les valeurs des paramètres sont supprimées des données de télémétrie et des journaux.

Préparer un avertissement

PREPARE ... AS SELECT $1 utilise la syntaxe positionnelle côté serveur PostgreSQL. L'extension détecte les instructions PREPARE et laisse des paramètres fictifs dans le corps de PREPARE pour PostgreSQL au lieu de les associer côté client. D’autres instructions du même script sont analysées normalement.

Cas MVP non pris en charge

Le MVP n’inclut pas :

  • Historique persistant des valeurs stockées sur disque.
  • Ensembles de paramètres nommés ou enregistrés entre les sessions de l'éditeur.
  • Réutilisation côté PREPARE/EXECUTE serveur en tant qu’exécution paramétrable côté client.
  • Composite, tableau, bytea, plage, intervalle, énumération ou autre liaison de type au-delà des types de liste déroulante pris en charge.

Contenu connexe

  • Last updated on