[client-v2, jdbc-v2] Server bound query parameters

[chernser]

Description

There is a minimal support of server side query parameters but there are ways to improve and issues to fix.

What need to be done:

• Examples
• fix UX issues. define place of value converters and encoding
• port JDBC v1 approach with PreparedStatement

[github-actions]

Triage Report

Effort to Fix: Medium
Type: Feature Request / Enhancement
Affected Module: client-api-v2, jdbc-v2

Summary

The client-v2 module has minimal server-side query parameter support (Client.query(sql, Map<String,Object>)) but the encoding is naive (String.valueOf(v)) with no type-aware conversion or proper ClickHouse escaping. The jdbc-v2 PreparedStatementImpl uses client-side ?-placeholder substitution and has no path to use ClickHouse's server-bound named parameters; this support existed in jdbc-v1 via useNamedParameter with :name(Type) syntax and needs to be ported to v2.

Recommended Labels & Priority

• Labels: client-api-v2, jdbc-v2, area:client-read, area:sql-parser, area:docs

Missing Information / Questions for User

1. Should jdbc-v2 PreparedStatement route all parameterized queries to server-side named params, or only opt-in via a connection property (mirroring the v1 use_named_parameter flag)?
2. What ClickHouse data types need first-class encoding support in the parameter serializer (e.g. DateTime64, Array, Tuple, Nullable, UUID)?
3. Are there known server-version constraints — i.e., is there a minimum ClickHouse server version that reliably supports all the required param_* query-string features?
4. Should the value-converter/encoder live inside client-v2 (shared) or be duplicated per module?

Tests to Add

Test 1: Type-aware parameter encoding in client-v2

// Verify that DateTime64, UUID, Array values are correctly encoded
// as ClickHouse server-side param_* query parameters and round-trip correctly.
@Test
void testServerBoundParamsTyped() throws Exception {
    Map<String, Object> params = new HashMap<>();
    params.put("ts", ZonedDateTime.now(ZoneOffset.UTC));
    params.put("id", UUID.randomUUID());
    params.put("arr", new int[]{1, 2, 3});

    try (QueryResponse resp = client.query(
            "SELECT {ts:DateTime64(3)}, {id:UUID}, {arr:Array(Int32)}",
            params, null).get()) {
        ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(resp);
        Assert.assertNotNull(reader.next());
    }
}

Test 2: jdbc-v2 PreparedStatement with server-bound named parameters

// Verify that PreparedStatement can forward parameters to the server
// using the param_* mechanism instead of client-side substitution.
@Test
void testPreparedStatementServerBoundParams() throws Exception {
    try (Connection conn = dataSource.getConnection();
         PreparedStatement ps = conn.prepareStatement(
                 "SELECT * FROM system.numbers WHERE number = {n:UInt64} LIMIT 1")) {
        ps.setLong(1, 42L);
        try (ResultSet rs = ps.executeQuery()) {
            Assert.assertTrue(rs.next());
            Assert.assertEquals(rs.getLong(1), 42L);
        }
    }
}