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

[sankalpsthakur]

Summary

Hardens multi-host (HA) DSN address parsing so host lists stay intact across net/url host-normalization differences (including Go 1.26-era multi-host / HA DSN breakage reported in #1784).

fromDSN already uses churl.Parse (from #1787). This change additionally extracts the HA host list from the raw DSN authority instead of only strings.Split(dsn.Host, ","), so:

• IPv4 multi-host DSNs keep every peer (host1:9440,host2:9440)
• Bracketed IPv6 multi-host DSNs keep every peer ([::1]:9440,[2001:db8::1]:9440) instead of collapsing to the last host
• Auth / query / path continue to come from the parsed URL

Changes

• dsnAddrList / addrListFromDSN / splitHostList in clickhouse_options.go
• ParseDSN regression cases for issue 1784 (auth+secure, HTTP HA, IPv6 HA)
• Unit tests for host-list helpers
• lib/churl multi-host parse tests

Fixes #1784

Checklist

• Unit and integration tests covering the common scenarios were added
• For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

Validation

go test -count=1 -run 'TestParseDSN|TestDSNAddrList|TestSplitHostList' .
go test -count=1 ./lib/churl/
go test -count=1 .

Results (Go 1.26.0):

ok  github.com/ClickHouse/clickhouse-go/v2          (TestParseDSN + helpers PASS)
ok  github.com/ClickHouse/clickhouse-go/v2/lib/churl (TestParseMultiHost PASS)
ok  github.com/ClickHouse/clickhouse-go/v2          (package unit tests PASS)

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]

we do not name tests after issues - tests should match functionality
please remove.

[chernser]

what user and password would be used for second host?
what if credentials are overridden in options?
There should be tests for all this cases.

[chernser]

There are already tools that can parse such form of url:

package main

import (
	"fmt"
	"net"
	"net/url"
	"strings"
)

type TargetHost struct {
	Host string
	Port string
}

func main() {
	rawURL := "clickhouse://user:pass@host1:9440,host2:9440/database?secure=true"

	// 1. Parse into a standard URL structure
	u, err := url.Parse(rawURL)
	if err != nil {
		panic(err)
	}

	// 2. Extract Username
	username := ""
	if u.User != nil {
		username = u.User.Username()
	}

	// 3. Extract the complete host cluster string
	// u.Host will contain "host1:9440,host2:9440"
	clusterStr := u.Host

	// 4. Split the individual hosts by comma
	hostTokens := strings.Split(clusterStr, ",")
	var hosts []TargetHost

	for _, token := range hostTokens {
		h, p, err := net.SplitHostPort(token)
		if err != nil {
			// Fallback if port is missing from a specific host token
			h = token
			p = ""
		}
		hosts = append(hosts, TargetHost{Host: h, Port: p})
	}

	// Output results
	fmt.Println("Username:", username)
	fmt.Println("Database:", strings.TrimPrefix(u.Path, "/"))
	fmt.Println("Hosts found:")
	for i, h := range hosts {
		fmt.Printf("  [%d] Host: %s, Port: %s\n", i, h.Host, h.Port)
	}
}

[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.