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

PublicadoHerramientaAnalizador de binding de parámetros SQL

Contenido
  1. ¿Por qué los valores no se rellenan como esperas?
  2. Las reglas para sustituir valores a mano, sin herramientas
  3. Errores de interpretación habituales y cómo leer el resultado
  4. En resumen
  5. Preguntas frecuentes

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 y null·true·false van sin comillas, el resto de cadenas se encierra en comillas simples, y PostgreSQL escapa ' como '' mientras que MySQL·SQLite lo escapan como \'. ③ Los ?·:name que 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. $1 es el primer valor y $2, el segundo.
  • Nominal: :name, @name y $name se 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, true y false (sin distinguir mayúsculas y minúsculas) se escriben como las palabras clave NULL, TRUE y FALSE, 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.

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 introducidoRepresentación en el resultadoMotivo
2525Un número puro va sin comillas
null / TRUE / falseNULL / TRUE / FALSESe 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·false van tal cual; el resto, entre comillas simples.
  • El escapado de comillas depende de la base de datos: '' en PostgreSQL y \' en MySQL·SQLite.
  • Los ?·:name dentro 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.
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.

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

Artículos relacionados

  1. Escapar cadenas de texto en JSON y JS: qué cambia y cómoTabla con los símbolos que sustituyen a barras invertidas, comillas, saltos de línea y tabulaciones en JSON y JS, el sentido inverso y los errores más comunes.
  2. Quitar etiquetas HTML: deja solo el texto planoCómo quitar las etiquetas HTML de un texto copiado y dejar solo el cuerpo: con una regex en tu editor o con la herramienta, y qué cambia cada opción.
  3. Conversor de superíndices y subíndices: x² y H₂O para copiarAprende a escribir x² y H₂O con caracteres Unicode reales que se mantienen al pegarlos en mensajes, redes o documentos, y por qué algunos no cambian.
  4. Coordenadas de ruta SVG: leer el atributo d y pasarlo a JSONAprende a leer las letras y números del atributo d (M, L, C, Z), a distinguir mayúsculas de minúsculas y a extraer las coordenadas en JSON, puntos o CSV.
  5. Convertir SVG en componente React: qué cambia realmenteAl pegar SVG en JSX, atributos como stroke-width o class generan advertencias. Aprende la regla camelCase, el patrón {...props} y nombres de componente.
  6. Texto a binario UTF-8: cómo se convierte cada letra en 0 y 1Cómo pasa un texto a ceros y unos con UTF-8: por qué el inglés ocupa 1 byte, el coreano 3 y los emojis 4, y cómo se recupera el texto.

Herramientas relacionadas