Binding de parámetros SQL: cómo se sustituyen los valores

Contenido
Para ver con tus propios ojos cómo se sustituyen los valores reales en una consulta SQL con placeholders como ?, :id o @name hasta llegar a la consulta final, basta con conocer cuatro reglas. Los números y null·true·false van tal cual, sin comillas; las cadenas se envuelven en comillas simples; y no se toca lo que está dentro de las comillas ni los comentarios. Esa es la clave.
Este artículo explica cómo aplicar esas reglas a mano y cómo comprobar el resultado al instante. Es lo que necesita un desarrollador que quiera reproducir una consulta con ? que vio en un log, o cualquiera que sienta curiosidad por saber cómo rellena los valores el driver.
Resumen ① Los posicionales (
?,$1) se rellenan en el orden de los valores; los nominales (:name,@name,$name), por nombre coincidente; y el JSON, por orden si es un array y por nombre si es un objeto. ② Los números ynull·true·falsevan sin comillas, el resto de cadenas se encierra en comillas simples, y PostgreSQL escapa'como''mientras que MySQL·SQLite lo escapan como\'. ③ Los?·:nameque están dentro de una constante de cadena'...'o de un comentario (--,/* */) no son placeholders reales, así que se dejan tal cual.
¿Por qué los valores no se rellenan como esperas?
En los logs de la aplicación o en la salida de depuración de un ORM es habitual encontrar la consulta tal cual, antes de que se sustituyan los valores: en estado WHERE id = ? o WHERE id = :id.
Para reproducir el problema necesitas la consulta final con los valores reales en su sitio, pero al insertarlos a mano es fácil equivocarse: olvidar las comillas en una cadena o dar por hecho que se rellenó algo cuyo nombre no coincidía.
Hay dos situaciones en las que el resultado se sale de lo esperado. Si escribiste la consulta en modo nominal pero hay un ? mezclado, ese ? no se rellena; y si es posicional y el número de valores no coincide con el de placeholders, sobran o faltan posiciones. Las reglas explican por qué.
Las reglas para sustituir valores a mano, sin herramientas
El binding tiene dos pasos: localizar dónde están los placeholders reales y escribir en cada sitio el valor con el formato adecuado. Si aplicas las reglas en orden, puedes construir la consulta final a mano.
Paso 1 — determina el modo de los placeholders. Los tres modos asocian los valores de forma distinta.
- Posicional: se rellenan
?y$1,$2… en el orden de los valores.$1es el primer valor y$2, el segundo. - Nominal:
:name,@namey$namese emparejan con el valor que tiene el mismo nombre. El orden no importa. - JSON: si le pasas un array
[...], funciona como el posicional; si le pasas un objeto{...}, como el nominal.
Paso 2 — escribe el valor con el formato adecuado. El «aspecto» del valor determina si lleva comillas o no.
- Los números puros (
25,-3,25.5) se escriben tal cual, sin comillas. null,trueyfalse(sin distinguir mayúsculas y minúsculas) se escriben como las palabras claveNULL,TRUEyFALSE, respectivamente.- Cualquier otro valor se trata como cadena y se encierra en comillas simples.
Paso 3 — escapa las comillas dentro de la cadena. Si el valor contiene una comilla simple, cada base de datos la trata de forma distinta.
- PostgreSQL:
'se convierte en''(dos comillas simples).O'Brien→'O''Brien' - MySQL·MariaDB·SQLite:
'se convierte en\'y la barra invertida\en\\.O'Brien→'O\'Brien'
Paso 4 — no toques las constantes de cadena ni los comentarios. Es la parte en la que más fácil es equivocarse cuando lo haces a mano.
Si la consulta ya contiene un signo de interrogación entre comillas, como '?', o un interrogante dentro de un comentario, como -- nota ?, no es un placeholder. Todo lo que está dentro de '...', en la línea que sigue a -- y entre /* */ se deja exactamente como está.
Por ejemplo, si a SELECT '?' AS mark FROM t WHERE id = ? le pasas el valor posicional 5, el '?' del principio se queda igual y solo el ? del final se rellena con 5. El resultado es SELECT '?' AS mark FROM t WHERE id = 5.
Compruébalo con el Analizador de binding de parámetros SQL.
Funciona directamente en el navegador, sin instalación ni inicio de sesión. Compatible con las reglas de escapado y el orden de MySQL, PostgreSQL y SQLite, y con entradas posicionales, por nombre y JSON.

Errores de interpretación habituales y cómo leer el resultado
Empecemos por cómo se representa el resultado según el aspecto del valor.
| Valor introducido | Representación en el resultado | Motivo |
|---|---|---|
| 25 | 25 | Un número puro va sin comillas |
| null / TRUE / false | NULL / TRUE / FALSE | Se reconoce como palabra clave (sin distinguir mayúsculas) |
| administrator | 'administrator' | Las cadenas se encierran en comillas simples |
| O'Brien (PostgreSQL) | 'O''Brien' | ' se escapa como '' |
| O'Brien (MySQL·SQLite) | 'O'Brien' | ' se escapa como \' |
Modo nominal y el ? sigue ahí. El modo nominal busca los valores solo por nombre. Como ? no tiene nombre, no es un destino al que asignar nada y se queda como ?. El ejemplo por defecto de la pantalla anterior es justo esta situación: :min_age y @user_role recibieron su valor, pero el ? sigue igual. Si mezclaste posiciones posicionales y nominales en una misma consulta, tienes que unificar el modo.
Cuando los nombres no coinciden. En el modo nominal, si la consulta pide :user_id y el valor se llama userId, la ortografía no coincide, no se encuentran y :user_id se queda como está. Si ves un nombre sin rellenar en el resultado, sospecha de una errata.
Modo posicional con un número de valores que no encaja. Si hay menos valores que placeholders, las posiciones que faltan se rellenan con NULL; si hay más valores, los que sobran se ignoran. Por ejemplo, si a VALUES (?, ?, ?) le pasas solo dos valores (1, hello), obtienes VALUES (1, 'hello', NULL).
Cuando quieres introducir la cadena 'null'. Como la decisión se toma por el aspecto del valor, si escribes null no obtienes una cadena sino la palabra clave NULL. Y 007, aunque tenga un cero delante, tiene forma de número puro y sale sin comillas como 007. El resultado puede no ser lo que pretendías, así que lo más seguro es comprobarlo con tus propios ojos.
Por último, algo que no conviene malinterpretar: que esta herramienta escape las comillas no significa que frene la inyección SQL. Es un simulador de composición para ver la consulta final con tus propios ojos; en el código real del servidor no concatenes valores en una cadena: usa un PreparedStatement o el binding nativo del driver.
En resumen
- Los tres modos se guían por criterios distintos: el posicional por el orden, el nominal por el nombre y el JSON por el orden si es un array o por el nombre si es un objeto.
- El aspecto del valor decide las comillas. Los números puros y
null·true·falsevan tal cual; el resto, entre comillas simples. - El escapado de comillas depende de la base de datos:
''en PostgreSQL y\'en MySQL·SQLite. - Los
?·:namedentro de constantes de cadena y comentarios no son placeholders y se quedan tal cual. - Esta herramienta es un simulador de composición para comprobar el resultado. En el código real del servidor, lo estándar es usar un PreparedStatement o el binding nativo de parámetros.
Funciona directamente en el navegador, sin instalación ni inicio de sesión. Compatible con las reglas de escapado y el orden de MySQL, PostgreSQL y SQLite, y con entradas posicionales, por nombre y JSON.
Preguntas frecuentes
¿Los ? que están dentro de una cadena o de un comentario también se sustituyen por valores?
No. Los ? o :name que aparecen dentro de una constante de cadena entre comillas simples '...', de un comentario de una línea -- o de un comentario de bloque /* */ no son placeholders reales, así que se dejan tal cual. La herramienta recorre la consulta carácter a carácter y determina si en cada punto estás dentro de una cadena o de un comentario, por eso la consulta no se rompe.
Estoy en el modo de nombres de variable y los ? no cambian, se quedan igual.
Es normal. El modo de nombres de variable solo rellena los nombres (:name, @name, $name) que coinciden. El ? no tiene nombre, así que no es un destino que rellenar y permanece igual. Si quieres rellenar los ?, cambia al modo posicional o unifica los placeholders de la consulta en un solo estilo.
¿Y si estoy en el modo posicional y hay menos valores que placeholders?
Las posiciones que faltan se rellenan con NULL, y si hay más valores, los sobrantes se ignoran. Si en la consulta resultante ves un NULL que no esperabas, comprueba que el número de líneas de valores coincida con el número de ? y de $n.
¿Puedo ejecutar tal cual la consulta que genera esta herramienta?
Conviene verla como un simulador de composición para aprender, reproducir y depurar. En una aplicación real, lo estándar es usar PreparedStatement o el binding nativo del driver en lugar de concatenar los valores a mano.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano