Ejecución de consultas con parámetros

Las consultas con parámetros permiten mantener los marcadores de posición en SQL y proporcionar valores en tiempo de ejecución. La extensión PostgreSQL enlaza esos valores como parámetros de consulta; no pega valores en el texto SQL.

Use esta página cuando desee ejecutar SQL copiado de herramientas o código de aplicación que use marcadores de posición como :name, $1o ?.

Sintaxis de marcador de posición admitida

El editor de consultas detecta estos estilos de marcador de posición fuera de cadenas, comentarios, conversiones, segmentos de matriz, cuerpos entre comillas de dólar y operadores JSON de PostgreSQL.

Marcadores de posición con nombre

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

Los marcadores de posición con nombre distinguen mayúsculas de minúsculas. Las repeticiones repetidas del mismo nombre comparten una fila de cuadrícula.

Marcadores de posición posicionales de PostgreSQL

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

$N los marcadores de posición ocupan una posición fija dentro de la instrucción que los contiene.

Marcadores de posición posicionales de Qmark

select id, email
from users
where active = ?;

? Los marcadores de posición siguen un orden de izquierda a derecha. ?, en cualquier posición de valor, actúa como parámetro, incluso después de los operadores de comparación (>=, <=, <>), en las ramas CASE y en LIMIT/OFFSET. Los operadores JSONB de PostgreSQL ?, ?| y ?&, y el operador de ruta JSON @?, se reconocen como operadores, no como parámetros.

Abra y use la pestaña Parámetros.

1. Abra o cree un .sql archivo y conéctelo a una base de datos.
2. Ejecute Execute Query (PostgreSQL),Execute Current Statement (PostgreSQL) o ejecute un intervalo SQL seleccionado.
3. Si SQL contiene marcadores de posición, la pestaña Parámetros se abre en el panel inferior.
4. Escriba un valor para cada fila, elija un tipo si es necesario y seleccione Ejecutar consulta.
5. Después de la primera ejecución, edite los valores y seleccione Ejecutar de nuevo para repetir la consulta.

La pestaña muestra una fila para cada marcador de posición con nombre único y una fila para cada marcador de posición posicional. Cada fila incluye el nombre o índice del marcador de posición, una entrada de valor, una casilla NULL , una lista desplegable de tipos y acciones de fila cuando estén disponibles.

Secuencias de comandos de varias sentencias

Nota (mayo de 2026): las versiones anteriores de este artículo describían incorrectamente los índices posicionales como independientes de cada instrucción. El comportamiento no cambió; solo se corrige la documentación.

Los parámetros posicionales ($N, ?) comparten una única matriz de valores en el script ejecutado. $1 (o el primer ?) en cualquier instrucción siempre se enlaza al mismo valor que $1 en cualquier otra instrucción. La reutilización del mismo índice posicional entre instrucciones no les proporciona valores independientes. Si necesita valores diferentes para el mismo índice en instrucciones diferentes, use parámetros con nombre (:name) en su lugar.

Si un valor con nombre compartido no es compatible con una de las instrucciones que la usa, PostgreSQL devuelve el error y la cuadrícula mantiene los valores para que pueda ajustar y ejecutar de nuevo.

Valores NULL

Use la casilla de verificación NULL para enlazar SQL NULL. Cuando está marcada, el campo de valor se ignora para esa fila.

Si escribe el texto NULL literal mientras la casilla NULL está desactivada, la cuadrícula le advierte de que el valor se enlaza como texto NULL, no SQL NULL.

Elegir tipos de parámetros

La lista desplegable de tipos tiene autocomo valor predeterminado , que permite a PostgreSQL deducir el tipo de parámetro. Elija un tipo cuando desee la validación del lado cliente o un enlace más claro:

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

La validación es flexible. Una advertencia no bloquea el envío; PostgreSQL sigue siendo el validador final en tiempo de ejecución.

Generación de un plan de consulta con parámetros

Al visualizar un plan de consulta para SQL que contiene marcadores de posición, la pestaña Parámetros controla el visualizador del plan de consulta en lugar de devolver filas. El botón Ejecutar muestra Visualizar el plan de consulta y, después de la primera ejecución, muestra Volver a visualizar. Escriba los valores y seleccione el botón para ejecutar EXPLAIN y abrir el visualizador del plan de consulta. Esta ruta de acceso no devuelve los resultados de la consulta.

Usar «Ignorar»

Use Ignore cuando la cuadrícula muestre un token que debe permanecer en SQL, como un operador postgreSQL válido. Ignorar solo está habilitado cuando el token sigue siendo un SQL válido sin vinculación.

Edición de SQL y ejecución de nuevo

Al abrir la pestaña Parámetros , puede editar SQL y seleccionar Ejecutar de nuevo. La extensión vuelve a extraer los marcadores de posición y compara el nuevo SQL parametrizado con la firma anterior.

Si el conjunto de marcadores de posición ha cambiado, un banner de desfase resume lo que ha cambiado, como los marcadores de posición agregados o eliminados. La extensión fusiona los valores hacia adelante cuando el marcador de posición sigue coincidiendo por nombre o por su índice de posición. Si se quitan todos los marcadores de posición, la cuadrícula se cierra y la consulta se ejecuta normalmente.

Cancelación y recuperación de transacciones

Mientras se activa una ejecución parametrizada, el botón Ejecutar cambia a un control stop (etiquetado como Cancelar). Cancelar interrumpe el lote en curso, omite los lotes siguientes y deja abierta la pestaña Parámetros con los valores intactos. Una ejecución cancelada muestra el estado del lote cancelado en lugar de un error, por lo que sus filas no se resaltan como errores.

La extensión no revierte automáticamente las transacciones iniciadas por el usuario. Si la cancelación deja la conexión en un estado de transacción anulada, la pestaña Parámetros muestra un aviso de recuperación con Ejecutar ROLLBACK. Selecciónelo para emitir un explícito ROLLBACK en la misma conexión y, a continuación, vuelva a ejecutar el script.

Revisión de errores y reintento

Cuando se produce un error en una ejecución con parámetros, la pestaña Parámetros mantiene los valores y muestra el estado con error con el resumen de errores de la base de datos. Seleccione Ver mensajes para abrir los detalles completos del mensaje.

Las ejecuciones canceladas muestran el estado de cancelación por separado del de las ejecuciones fallidas, y los lotes posteriores que no se ejecutaron se marcan como omitidos.

Después de corregir un valor o tipo, seleccione Ejecutar de nuevo. La pestaña borra el estado obsoleto de fallo, cancelación y resaltado de la fila para el nuevo intento. Si la conexión todavía está en una transacción anulada, el aviso de recuperación vuelve a aparecer.

Retención de valores del historial de consultas

La configuración pgsql.queryPlaceholders.historyValueRetention controla si los valores de parámetro se conservan en el historial de consultas en memoria de la sesión actual:

Cuando ask está activo, el mensaje que se muestra después de una ejecución satisfactoria ofrece Guardar una vez (conservar solo esta entrada), Guardar siempre (y cambiar también la configuración a always), Omitir (solo para SQL con plantillas) y No volver a preguntar (y cambiar también la configuración a never).

Los valores solo se conservan en memoria y se borran cuando VS Code se vuelve a cargar o cambia el área de trabajo. Los valores de parámetro se redactan de telemetría y registros.

PREPARAR salvedad

PREPARE ... AS SELECT $1 usa la sintaxis posicional del lado servidor de PostgreSQL. La extensión detecta instrucciones PREPARE y deja marcadores de posición dentro del cuerpo PREPARE de PostgreSQL en lugar de vincularlos en el cliente. Las demás sentencias del mismo script se analizan de forma normal.

Casos de MVP no compatibles

El MVP no incluye:

• Historial persistente de valores almacenado en disco.
• Conjuntos de parámetros con nombre o guardados entre distintas sesiones del editor.
• Reutilización en el servidor PREPARE/EXECUTE como ejecución parametrizada en el cliente.
• Compuesto, array, bytea, rango, intervalo, enumerado u otro tipo de vinculación más allá de los tipos admitidos en la lista desplegable.

Contenido relacionado

• Editor de consultas e IntelliSense
• Visualizador de planes de consulta
• Inicio rápido: Conexión y consulta de PostgreSQL
• Referencia de configuración