Named()/DateNamed() serialize server-side {name:Type} parameter values incorrectly for several types

[nm-yegor-parfenenka]

Observed

When using server-side query parameters ({name:Type} syntax with clickhouse.Named / clickhouse.DateNamed), the driver serializes several value types into text that ClickHouse cannot parse back, causing the query to fail:

1. Named("p", time.Time{}) for a {p:Date} parameter is sent as toDateTime('2026-05-15 00:00:00'), which the server rejects as a Date (code 38). The same reuse of the client-side formatter also affects Array(Date) / Array(DateTime) and Array(Bool) (codes 27 / 130).
2. String values inside array parameters are escaped with \', which the parameter parser rejects (code 25). Plain string parameters containing a newline or tab fail under server-side TSV parsing (code 457).
3. DateNamed formats the timestamp without a timezone, so the server interprets it in its own timezone — the bound instant shifts on any non-UTC server.

Expected behaviour

Values passed via Named / DateNamed for {name:Type} parameters should be serialized in the plain text format ClickHouse's parameter parser expects (e.g. 2026-05-15 for Date, true/false for Bool, unescaped/TSV-correct strings, timezone-anchored timestamps), so that any value valid for the declared type round-trips successfully.

Code example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/ClickHouse/clickhouse-go/v2"
)

func main() {
	conn, err := clickhouse.Open(&clickhouse.Options{
		Addr: []string{"127.0.0.1:9000"},
		Auth: clickhouse.Auth{Database: "default", Username: "default", Password: "pass"},
	})
	if err != nil {
		panic(err)
	}
	ctx := context.Background()

	run := func(name, sql string, args ...any) {
		rows, err := conn.Query(ctx, sql, args...)
		if err != nil {
			fmt.Printf("%s\n    ERROR: %v\n", name, err)
			return
		}
		rows.Close()
		fmt.Printf("%s\n    OK\n", name)
	}

	d := time.Date(2026, 5, 15, 0, 0, 0, 0, time.UTC)

	// 1. Named(time.Time) sends toDateTime('...'), invalid as a Date literal.
	run("1. {p:Date} bound with Named(time.Time)",
		"SELECT {p:Date}", clickhouse.Named("p", d))

	// 1b/1c. Array element formatting reuses the same formatter.
	run("1b. {p:Array(Bool)} bound with []bool",
		"SELECT {p:Array(Bool)}", clickhouse.Named("p", []bool{true}))
	run("1c. {p:Array(Date)} bound with []time.Time",
		"SELECT {p:Array(Date)}", clickhouse.Named("p", []time.Time{d}))

	// 2a. Single quote in an array element is escaped as \', rejected by the parser.
	run("2a. {p:Array(String)} element containing a single quote",
		"SELECT {p:Array(String)}", clickhouse.Named("p", []string{"it's"}))

	// 2b. String parameters are re-parsed with TSV escaping; newline fails.
	run("2b. {p:String} with embedded newline",
		"SELECT {p:String}", clickhouse.Named("p", "a\nb"))

	// 3. DateNamed formats without a timezone; result shifts on non-UTC servers.
	var got time.Time
	if err := conn.QueryRow(ctx, "SELECT {p:DateTime64(9)}",
		clickhouse.DateNamed("p", d, clickhouse.NanoSeconds)).Scan(&got); err != nil {
		fmt.Printf("3. {p:DateTime64(9)} bound with DateNamed\n    ERROR: %v\n", err)
	} else {
		fmt.Printf("3. {p:DateTime64(9)} bound with DateNamed\n    bound unix=%d, got unix=%d (differs when server TZ is not UTC)\n",
			d.Unix(), got.Unix())
	}
}

Error log

1. {p:Date} bound with Named(time.Time)
    ERROR: code: 38, message: Cannot parse date here: toDateTime: value toDateTime('2026-05-15 00:00:00') cannot be parsed as Date for query parameter 'p'
1b. {p:Array(Bool)} bound with []bool
    ERROR: code: 130, message: Cannot read array from text, expected comma or end of array, found '1': value [1] cannot be parsed as Array(Bool) for query parameter 'p'
1c. {p:Array(Date)} bound with []time.Time
    ERROR: code: 27, message: Cannot parse input: expected '\'' before: 'toDateTime(\'2026-05-15 00:00:00\')]': value [toDateTime('2026-05-15 00:00:00')] cannot be parsed as Array(Date) for query parameter 'p'
2a. {p:Array(String)} element containing a single quote
    ERROR: code: 25, message: Cannot parse escape sequence: value ['it\ cannot be parsed as Array(String) for query parameter 'p'
2b. {p:String} with embedded newline
    ERROR: code: 457, message: Value a
b cannot be parsed as String for query parameter 'p' because it isn't parsed completely: only 1 of 3 bytes was parsed: a

Details

Environment

• clickhouse-go version: v2.45.0
• Interface: ClickHouse API
• Go version: 1.26
• Operating system: macOS (arm64) / Linux
• ClickHouse version: 24.8
• Is it a ClickHouse Cloud? No (local clickhouse/clickhouse-server:24.8)
• ClickHouse Server non-default settings, if any: none (for case 3, set server TZ=Australia/Sydney to observe the shift)
• CREATE TABLE statements for tables involved: n/a — reproduces with SELECT {p:Type}, no tables
• Sample data for all these tables: n/a

[nm-yegor-parfenenka]

After filing this I searched the tracker and most of these are already reported — cross-linking so this doesn't duplicate them. The common root cause is query_parameters.go reusing the legacy format(timezone, Seconds, …) client-side formatter for server-side {name:Type} params.

Mapping the three numbered items above to existing issues:

• Item 1 — Named(time.Time) for {p:Date} sending toDateTime('…') (and the Array(Date)/Array(DateTime) variants, same root cause) → DateTime64 server-side parameter values silently truncated to seconds precision #1858. The Array(Bool) 1/0 sub-case is already fixed by fix: render bool query parameters as true/false (Array(Bool)) #1892 (merged), though not yet in a release (latest is v2.47.0, merged after).
• Item 2 — single-quote/backslash escaping inside array/string params → Backslash insert issue using named parameters #1576; plain string params with newline/tab failing server-side TSV parsing → fix: escape control characters in native TCP query parameters #1834, fix: escape control characters in query parameter values #1807 (and the underlying Doc/Bug: Query params behavior in clickhouse-go #1792).
• Item 3 — the timezone gap: DateNamed formats without a timezone, so a DateTime64 param shifts by the server's UTC offset on a non-UTC server (the old ? path emitted an explicit 'UTC'). I don't see this covered elsewhere.

If items 1 and 2 are fully tracked by the issues above, this can be narrowed to just item 3 (the timezone case) or closed as a duplicate — whichever you prefer.

[sankalpsthakur]

Looking into this — I'll open a PR fixing the Named/DateNamed server-side parameter serialization issues.

[sankalpsthakur]

Withdrawing my earlier claim — items 1–2 look covered by existing issues/PRs (#1858, #1576, #1792, and open PRs #1807/#1834 for control-char escaping). Leaving this for maintainers to narrow/close as duplicate rather than stacking another overlapping PR.