Proposal: Split SQL and parameters in query endpoint

[cliftonc]

I have just come across this project (as a long time Snowflake buyer / user) and am super excited by the potential, and started to build out a library for it for my open source BI platform (see https://www.drizby.com/), via https://github.com/cliftonc/drizzle-databend.

However, I immediately ran into what I think is potentially a major issue ...

The /v1/query HTTP endpoint currently accepts only a sql string field. Parameter binding is handled entirely client-side by bendsql: the driver parses the SQL AST to find placeholders (?, $1, :name), calls Param::as_sql_string() on each value, and sends the fully-interpolated SQL string to the server.

This architecture has inherent limitations:

1. Security — every client library must independently implement correct escaping. Any new language SDK will face the same problem. Given the prevalence of SQL injection attacks I think this really could be a problem (I think there are also separate issues in your Param::as_sql_string() functions related to escaping that should be addressed for SQL Injection).
2. Performance — the server cannot cache query plans across different parameter values since every execution is a unique SQL string.
3. Type fidelity — values are serialized to SQL text and re-parsed by the server.

Proposal

Add a params field to the /v1/query request body:

  {
    "sql": "SELECT * FROM users WHERE name = $1 AND age > $2",
    "params": ["O'Brien", 42]
  }

The server would bind parameters directly, eliminating client-side interpolation. This is how PostgreSQL ($1), MySQL (?), and most databases handle HTTP/wire protocol parameters.

Without this, ORM drivers (e.g., drizzle-databend) must pre-escape string values before passing them to bendsql, and convert numeric strings to actual numbers based on column type metadata — effectively reimplementing parts of what server-side binding would provide.

This would be non breaking - as you can just omit it and the sql would still be sql. I'd be happy to look at implementing via a PR, but not sure what your status re. external contributions is?

Related? databendlabs/databend#8802

[sundy-li]

Hi, the proposal looks good to me. We are now replacing the params inside bendsql (client-side way).

We welcome all external contributions if we can implement a pr for this issue (maybe you can implement it inside ast crate).

[cliftonc]

Ok, great! Just to be clear: I assume you mean I implement a PR in both the server rust side (the AST crate?) and then matching in the bendsql client?

[sundy-li]

If we have parameter support in the server rust side (the AST crate) , we can use this new endpoint (with params fields in http api) in bendsql.

[cliftonc]

@sundy-li now that the rust side is merged, I am looking at this side, and ideally need your advice before continuing:

1. $N placeholder handling with server-side params

The server-side implementation doesn't support $N placeholders (as they conflicted with column position refs like SELECT $1 FROM @stage). When a client connects to a server that supports server-side params, and the user's SQL contains $N placeholders, should I:

• (a) Return an error telling the user to use ? or :name instead
• (b) Fall back to client-side interpolation silently for $N queries
• (c) Rewrite $N to ? (with param reordering) before sending to the server

I'm leaning toward (a) to make the incompatibility explicit and avoid magic.

2. Server version threshold for enabling server-side params

Once the server PR lands, what nightly version should we use as the capability threshold in bendsql's Capability::from_server_version()? I assume we can use a placeholder for now and update it once the server feature is released? Not sure what your practice here is.

3. Backward compatibility strategy

When bendsql detects an older server (below the version threshold), it will fall back to client-side interpolation automatically. Is this the right approach, or would you prefer the client always sends params and lets the server ignore unknown fields?

[sundy-li]

Hi, good to see it landed.

$N placeholder handling with server-side params

I think we do nothing about this. Databend server side supports $N to query csv files. eg:
select $1, $2 from @stage_abc/a.csv

we should not take this as placeholder params.

Server version threshold for enabling server-side params

That's good to use capability flag.

Backward compatibility strategy

I prefer the client always sends params and lets the server ignore unknown fields, users could degrade the client version to query old server.

[cliftonc]

Ok; initial PR in #762