rs2 / restspace

6.4 String/SQL templates and bind parameters

Not every backend is JSON. For SQL databases you author the query as a string template, and RS2 handles parameters differently — and safely — by handing the binding job to the adapter rather than splicing strings itself.

String templates aren't spliced by the service

When the query envelope's query is a string (rather than a JSON object), the language is inferred as sql. The crucial behavior:

The query service never substitutes parameters into a string template itself. It passes the template, plus the validated parameter set, to the adapter — which binds them as real prepared-statement parameters.

So a SQL adapter receives something like the template SELECT … WHERE status = :status together with { status: "open" }, and uses the database driver's bind mechanism. The parameter values never become part of the SQL text, so there's no injection surface — the same guarantee the JSON path gives structurally, the SQL path gives through binding.

Validated params still apply

Everything from 6.2 still holds for string templates: params are collected from URL/query/body, coerced to their declared types, defaulted, and validated against the params schema before the query runs. The adapter receives a clean, typed, validated parameter set.

The reference adapter is JSON-only

The built-in reference adapter scans a data dataset and understands JSON templates only. Handed a string/SQL template, it declines with 501 (not implemented). String templates are for real SQL adapters wired in by the deployment (QueryStore capability). In other words:

  • JSON template → works out of the box against your data store.
  • String/SQL template → requires a SQL QueryStore adapter to be configured.

Choosing a template kind

  • Use a JSON template for querying your data store, Mongo, or Elastic — and for the safety and at-rest readability of structural substitution.
  • Use a string template only when targeting a SQL database through an adapter that binds parameters. Author it as plain SQL with named placeholders; let the adapter bind.

Next: the param schema mechanics — defaults and validation — that both template kinds rely on.

← Previous: 6.3 JSON templates · Manual home · Next: 6.5 Param schemas, defaults, validation →