Выполнение параметризованных запросов

Параметризованные запросы позволяют хранить заполнители в SQL и предоставлять значения во время выполнения. Расширение PostgreSQL привязывает эти значения в качестве параметров запроса; Он не вставляет значения в текст SQL.

Используйте эту страницу, если вы хотите запустить SQL, скопированный из средств или кода приложения, которые используют заполнители, например :name, $1или ?.

Поддерживаемые синтаксисы заполнителей

Редактор запросов обнаруживает эти стили заполнителей вне строк, комментариев, операций приведения типов, срезов массивов, доллар-цитируемых блоков и JSON-операторов PostgreSQL.

Именованные заполнители

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 = ?;

? Местозаполнители работают в порядке слева направо. ? в любой позиции значения служит параметром, в том числе после операторов сравнения (>=, <=, <>), в CASE-ветвях и в LIMIT/OFFSET. Операторы JSONB ?, ?| и ?& PostgreSQL, а также оператор путей JSON @?, распознаются как операторы, а не как параметры.

Important

Используйте один стиль заполнителя для каждой инструкции. Инструкция, в которой смешиваются :name и $N или $N и ?, отклоняется до выполнения.

Открытие и использование вкладки "Параметры"

  1. Откройте или создайте .sql файл и подключите его к базе данных.
  2. Запустите запрос выполнения (PostgreSQL),выполните текущую инструкцию (PostgreSQL) или запустите выбранный диапазон SQL.
  3. Если SQL содержит заполнители, вкладка "Параметры " откроется на нижней панели.
  4. Введите значение для каждой строки, выберите тип при необходимости и нажмите кнопку "Выполнить запрос".
  5. После первого запуска измените значения и снова нажмите кнопку "Выполнить ", чтобы повторить запрос.

На вкладке отображается одна строка для каждого уникального именованного заполнителя и одна строка для каждого позиционного заполнителя. Каждая строка включает имя или индекс заполнителя, поле ввода значения, флажок NULL, раскрывающийся список типов и действия для строки, если они доступны.

Скрипты с несколькими операторами

Примечание (май 2026 г.): в более ранних версиях этой статьи позиционные индексы ошибочно описывались как не зависящие от инструкции. Поведение не изменилось; Исправлена только документация.

Позиционные параметры ($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 и снова нажать кнопку "Выполнить". Расширение повторно извлекает заполнители и сравнивает новый шаблонный SQL с предыдущим отпечатком пальца.

Если набор заполнителей изменен, баннер смещения суммирует изменения, такие как заполнители, добавленные или удаленные. Расширение переносит значения вперёд, когда плейсхолдер по-прежнему совпадает по имени или позиционному индексу. Если все заполнители удалены, сетка закрывается и запрос выполняется нормально.

Отмена и восстановление транзакций

Во время выполнения запуска с параметрами кнопка запуска меняется на кнопку остановки (с надписью Отмена). Отмена прерывает выполнение текущего пакета, пропускает последующие пакеты и оставляет вкладку Параметры открытой с сохранёнными значениями. Отмененный запуск показывает состояние пакета отменен, а не состояние сбоя, поэтому его строки не выделяются как ошибки.

Расширение не выполняет автоматический откат транзакций, запущенных пользователем. Если отмена приводит к переходу соединения в состояние прерванной транзакции, на вкладке Параметры отображается сообщение о восстановлении с Execute ROLLBACK. Выберите этот параметр, чтобы выполнить один явный ROLLBACK в том же соединении, а затем снова запустите скрипт.

Проверка сбоев и повторных попыток

Если параметризованный запуск завершается сбоем, вкладка "Параметры " сохраняет значения и отображает состояние сбоя с сводкой об ошибке базы данных. Выберите "Просмотреть сообщения" , чтобы открыть полные сведения о сообщении.

Отмененные запуски отображаются со статусом «Отменено» отдельно от запусков со сбоем, а последующие пакеты, которые не были выполнены, помечаются как пропущенные.

После исправления значения или типа нажмите кнопку "Выполнить снова". Вкладка очищает устаревший сбой, отмену и состояние выделения строк для новой попытки. Если подключение по-прежнему находится в прерванной транзакции, уведомление о восстановлении появляется снова.

Хранение значений журнала запросов

pgsql.queryPlaceholders.historyValueRetention Параметр определяет, сохраняются ли значения параметров в журнале запросов текущего сеанса в памяти:

Ценность Behavior
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