From 4825420a42de57f2cd27b3468a064a1e9252b3ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ngh=C4=A9a=20Nguy=E1=BB=85n=20Ng=E1=BB=8Dc?= Date: Sat, 9 May 2026 16:50:40 +0700 Subject: [PATCH] dsn: document that usernames with colons require NewConfig() The DSN format uses ':' as the user/password separator, making it impossible to represent a username that contains a colon without ambiguity. There is no safe way to fix this in ParseDSN without breaking existing users who rely on the current first-colon behaviour for passwords that contain colons. Instead, document the limitation clearly in the ParseDSN godoc and point callers to NewConfig(), which has no such ambiguity. Fixes #1747 --- dsn.go | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/dsn.go b/dsn.go index 491e10f3..a80b3958 100644 --- a/dsn.go +++ b/dsn.go @@ -392,7 +392,13 @@ func (cfg *Config) FormatDSN() string { return buf.String() } -// ParseDSN parses the DSN string to a Config +// ParseDSN parses the DSN string to a Config. +// +// The DSN format is [user[:password]@][net[(addr)]]/dbname[?params]. +// Because the colon is used as the user/password separator, usernames that +// contain a colon cannot be represented unambiguously in the DSN string format. +// If your username contains a colon, use [NewConfig] and set the fields directly +// instead of constructing a DSN string. func ParseDSN(dsn string) (cfg *Config, err error) { // New config with some default values cfg = NewConfig()