运行参数化查询

参数化查询允许在 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 = ?;

? 占位符按从左到右的顺序工作。 在任何值位置中，? 都会作为参数，包括在比较运算符（>=、<=、<>）之后、在 CASE 分支中，以及在 LIMIT/OFFSET 中。 PostgreSQL 的 JSONB 运算符??|和 ?& JSON 路径运算符@?被识别为运算符，而不是参数。

Important

每个语句只使用一种占位符样式。 将 :name 与 $N 混用，或将 $N 与 ? 混用的语句，会在执行前被拒绝。

打开并使用“参数”选项卡

1. 打开或创建 .sql 文件并将其连接到数据库。
2. 运行 执行查询（PostgreSQL）、 执行当前语句（PostgreSQL）或运行所选 SQL 范围。
3. 如果 SQL 包含占位符，“ 参数 ”选项卡将在底部面板中打开。
4. 输入每行的值，根据需要选择类型，然后选择 “运行查询”。
5. 首次运行后，编辑值并选择 “再次运行 ”以重复查询。

Visual Studio Code

游标

此选项卡会为每个唯一的命名占位符显示一行，并为每个位置占位符显示一行。 每行包括占位符名称或索引、值输入、 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 运算符）时，请使用 Ignore 。 仅在该标记在不进行绑定的情况下仍为有效 SQL 时，才会启用忽略功能。

编辑 SQL 并再次运行

打开“ 参数 ”选项卡时，可以编辑 SQL 并选择 “再次运行”。 该扩展重新提取占位符，并将新的模板化 SQL 与以前的指纹进行比较。

如果占位符集已更改，偏移横幅将汇总已更改的内容，例如添加或删除占位符。 当占位符仍按名称或位置索引匹配时，扩展会向前合并值。 如果删除了所有占位符，网格将关闭，查询将正常运行。

取消和恢复事务

当参数化运行处于活动状态时，运行按钮将更改为 停止 控件（标记为 “取消”）。 取消会中断当前正在执行的批次，跳过后续批次，并使 参数 选项卡保持打开，参数值不变。 已取消的运行显示已取消批处理状态，而不是失败，因此不会将其行突出显示为错误。

该扩展不会自动回滚用户启动的事务。 如果取消使连接处于中止的事务状态，则 “参数 ”选项卡会显示一个恢复通知，其中包含 “执行 ROLLBACK”。 选中此项，以便在同一连接上发出一个显式 ROLLBACK，然后再次运行脚本。

查看失败并重试

参数化运行失败时， “参数 ”选项卡会保留值，并显示失败状态，并显示数据库错误摘要。 选择“ 查看消息 ”以打开完整的邮件详细信息。

已取消的运行会以单独的“已取消”状态显示，与失败的运行区分开来，而未运行的后续批次则会被标记为“已跳过”。

修复值或类型后，再次选择“ 运行”。 此选项卡会为新尝试清除过时的失败、取消和行突出显示状态。 如果连接仍处于已中止的事务中，恢复通知将再次显示。

查询历史记录值保留

该设置 pgsql.queryPlaceholders.historyValueRetention 控制参数值是否保留在当前会话的内存中查询历史记录中：

价值	Behavior
ask	在每次成功参数化运行后询问。
always	在不提示的情况下保留会话内历史记录条目的值。
never	仅保留模板化的 SQL。

当 ask 处于活动状态时，成功运行后显示的提示会提供以下选项：保存一次（仅保留此条目）、始终保存（同时将设置切换为 always）、跳过（仅适用于模板化 SQL），以及 不要再询问（同时将设置切换为 never）。

值仅保留在内存中，当 VS Code 重载或工作区更改时将清除。 参数值会从遥测数据和日志中删去。

PREPARE 注意事项

PREPARE ... AS SELECT $1 使用 PostgreSQL 服务器端位置语法。 该扩展会检测 PREPARE 语句，并将占位符保留在 PREPARE 主体内交由 PostgreSQL 处理，而不是在客户端进行绑定。 同一脚本中的其他语句会被正常解析。

不支持的 MVP 大小写

MVP 不包括：

• 基于永久性磁盘的值历史记录。
• 跨编辑器会话的已命名或已保存参数集。
• 服务器端 PREPARE/EXECUTE 重用为客户端参数化执行。
• 超出受支持的下拉列表类型范围的复合、数组、bytea、范围、间隔、枚举或其他类型绑定。

相关内容

• 查询编辑器和 IntelliSense
• 查询计划可视化工具
• 快速入门：连接和查询 PostgreSQL
• 设置参考