fix: preserve multi-host HA DSN addresses (Go 1.26)

[sankalpsthakur]

Summary

Fixes #1784

Hardens multi-host (HA) DSN address parsing so host lists stay intact on Go 1.26.

DSN parsing uses net/url.Parse. When Go 1.26 rejects or collapses a comma-separated host list (http(s) with GODEBUG=urlstrictcolons, or bracketed IPv6 lists), a single-host rewrite is parsed and peers are restored with strings.Split and net.SplitHostPort.

• IPv4 multi-host keeps every peer
• Bracketed IPv6 multi-host keeps every peer
• Auth is cluster-wide (userinfo, username/password query override, and post-ParseDSN Options.Auth mutation)

Validation

• go test for ParseDSN / SplitHostList / MultiHostAuth / HTTP strict-colons (Go 1.25.6 and Go 1.26.7)
• Integration: TestMultiHostDSNFailover and TestMultiHostDSNAuthOverride (existing tests/conn_test.go pattern; not run locally without ClickHouse)

AI/LLM disclosure

• AI coding tools (including Grok and/or Codex agent-assisted editing) were used to help draft or modify code and this PR description.
• I reviewed the complete change, understand the reasoning, and ran the reported local tests before submitting.
• This submission is original work of authorship under the project CLA / contributor terms; AI output was not pasted unreviewed.

[chernser]

• correct implementation - use std lib
• documentation how it works and changelog
• more tests with authentication
• ideally integration test

[sankalpsthakur]

Thanks @chernser, addressed the feedback in the latest push. Documented lib/churl and refactored splitHostList to use net.SplitHostPort and JoinHostPort, expanded docs and added a changelog entry. Added more auth tests for multi-host cases including query overrides and IPv6. Unit tests pass. Let me know if you want integration coverage as well.

[sankalpsthakur]

Thanks @chernser, pushed c54255c to address the checklist. Please take another look when you have a moment.

[github-actions]

🤖 Claude review

Hardens multi-host HA DSN parsing (#1784) by extracting the host list from the raw DSN authority instead of relying on churl's parsed Host. The fix works for the reported cases (IPv4 multi-host, all-bracketed IPv6, auth variants) and the TestParseDSN coverage is solid, but the approach patches around the real bug in lib/churl and regresses percent-encoded hosts.

Key concerns:

• The raw-authority extraction takes precedence for every DSN and skips percent-decoding, so previously-working encoded hosts (RFC 6874 IPv6 zone IDs like [fe80::1%25eth0]:9000) now land encoded in Options.Addr and fail to dial (inline on clickhouse_options.go).
• Mixed bracketed + plain host lists ([::1]:9440,host2:9440) still fail end-to-end inside churl.Parse before the new code ever runs, while the new TestSplitHostList case suggests they are supported (inline on clickhouse_options_test.go).
• The root cause is churl.parseHost mishandling bracketed IPv6 in comma lists; fixing it there would resolve both inline findings, keep dsn.Host correct for all consumers, and avoid a second parser that must stay in sync with churl (see general finding).

Blind spots: this review is static — the sandbox could not run go test; the churl.parseHost traces were verified by hand against the copied Go 1.25.7 code in lib/churl/churl.go.

Verdict: ⚠️ Request changes

General findings

• ⚠️ Should fix — fix belongs in lib/churl.parseHost, not a second parser
  lib/churl exists precisely to keep comma-separated HA hosts parseable, yet parseHost still mishandles bracketed IPv6 lists: [a]:p,[b]:p silently collapses to the last host (it anchors on strings.LastIndex(host, "[")), and [a]:p,plain:p hard-errors on the port check. This PR works around that in fromDSN with a raw-string re-parse that must now agree with churl forever, while dsn.Host remains wrong for any other consumer of churl.Parse.

  Splitting the authority on top-level commas inside parseHost (reusing the bracket-depth logic from splitHostList) and parsing each host individually would fix both inline findings at the root, keep the existing strings.Split(dsn.Host, ",") in fromDSN working unchanged, and remove the ~95 new lines in clickhouse_options.go.

_{Inline comments are attached to the relevant lines. This summary updates in place on re-review.}

[sankalpsthakur]

@chernser rebased on main. multi-host split lives in lib/churl.parseHost now (IPv6/mixed/zone IDs), fromDSN just uses SplitHostPort. more tests + multi-host failover. d1c8f2f.

[sankalpsthakur]

@chernser follow-up on 74b1af5: cluster-wide Auth test (userinfo, query override, post-ParseDSN Options mutation) and README notes for multi-host IPv6 / failover auth.

Earlier (d1c8f2f): multi-host split in lib/churl.parseHost; fromDSN only SplitHostPort/JoinHostPort. Integration: TestMultiHostDSNFailover. Ready when you have a moment.

[sankalpsthakur]

Updated this for the stdlib-style multi-host parsing notes, auth/override cases, changelog, and renamed the tests off the issue number. Ready for another pass when you have time.

[sankalpsthakur]

Merged latest main, normalized the CHANGELOG Unreleased note (CRLF), and documented multi-host DSN / cluster-wide Auth in docs/configuration.mdx, docs/database-sql-api.mdx, and docs/config-reference.mdx.

Review checklist remains covered: stdlib SplitHostPort/JoinHostPort after lib/churl.parseHost, auth override tests, integration TestMultiHostDSNFailover. Unit tests for ParseDSN / SplitHostList / MultiHostAuth / churl pass locally.

[sankalpsthakur]

Pushed ae9f6d5. After churl.Parse, hosts split with strings.Split + SplitHostPort. TestMultiHostDSNAuthOverride covers replacing Options.Auth after ParseDSN, including failover to the live host.

[sankalpsthakur]

Rebased onto current main to clear the merge conflict. Stdlib SplitHostPort after churl.Parse, cluster-wide auth tests, and the failover integration tests are unchanged.

[sankalpsthakur]

@chernser HA DSN parsing now uses net/url.Parse plus strings.Split and net.SplitHostPort, without a custom authority parser in lib/churl. Multi-host lists that Go 1.26 rejects or collapses are recovered by parsing a single-host rewrite. Auth is cluster-wide (userinfo, query username/password, Options.Auth after ParseDSN). Docs and changelog updated. Unit tests cover auth/IPv6 on Go 1.25 and 1.26; failover tests remain in tests/conn_test.go.