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

Author: Nghĩa Nguyễn Ngọc

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()