dsn: document that usernames containing colons require NewConfig()

[nghiack7]

Updated Approach

After the maintainer review (thank you @shogo82148 and @methane), I've updated this PR to be documentation-only — no behavioral change.

What changed

Added a godoc note to ParseDSN explaining the fundamental ambiguity:

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

Why this approach

The original fix (last colon) broke passwords containing colons — a symmetric bug to the one it was fixing. There is no unambiguous parse rule for the user:password@ portion when either field can contain a colon.

The correct solution is to steer users to NewConfig(), which has no such ambiguity.

Fixes #1747

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 10c16305-3da1-4db2-a000-ffece18357cb

📥 Commits

Reviewing files that changed from the base of the PR and between bff59f9 and 4825420.

📒 Files selected for processing (1)

• dsn.go

✅ Files skipped from review due to trivial changes (1)

• dsn.go

---

Walkthrough

The PR expands ParseDSN function documentation to clarify the DSN format syntax and explain the structural limitation that usernames containing colons cannot be unambiguously parsed using the : separator, directing affected users to use NewConfig instead.

Changes

DSN Documentation Update

Layer / File(s)	Summary
Documentation Clarification dsn.go	ParseDSN doc comment is extended to show full DSN syntax and explicitly document that colons in usernames create ambiguity, recommending NewConfig for such cases.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the primary change: documentation addition explaining that usernames with colons require NewConfig().
Description check	✅ Passed	The description is related to the changeset, explaining the documentation-only approach and the rationale for not modifying parsing logic.
Linked Issues check	✅ Passed	The PR addresses issue #1747 by providing documentation that guides users with colons in usernames to use NewConfig() instead of ParseDSN [#1747].
Out of Scope Changes check	✅ Passed	The changes are narrowly scoped: only documentation comments were added to ParseDSN with no behavioral modifications or unrelated changes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.1)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coveralls]

coverage: 82.603% (-0.1%) from 82.701% — nghiack7:fix/ParseDSN-colon-in-username into go-sql-driver:master

[shogo82148]

Hmmm...
Users with a colon (:) in their password will get different results compared to previous versions.

As @methane says, I recommend using NewConfig().

#1747 (comment)

[nghiack7]

Thank you for the review @shogo82148 and for linking the maintainer's recommendation.

You're correct — using the last colon before @ solves the colon-in-username case but introduces a symmetric breakage: users with colons in their passwords (who currently rely on the first-colon split) would get wrong results after upgrading.

Both interpretations are valid reads of the DSN format, so the DSN syntax itself is fundamentally ambiguous for this case. There is no unambiguous fix within ParseDSN.

Given @methane's recommendation to use NewConfig() instead, I see two options:

1. Close this PR — document the limitation in the issue and recommend NewConfig() as the canonical solution for usernames with colons.
2. Documentation-only change — add a note to ParseDSN's godoc explaining the ambiguity and pointing to NewConfig().

Happy to update to option 2 if that would be accepted, or close if the preference is to keep ParseDSN unchanged. What would you prefer?

[shogo82148]

LGTM

+1 for option 2

[methane]

It seems odd that the DSN has many constraints, but only the characters that cannot be used in the username are mentioned. It gives the impression that there are no other major constraints.

Additonally, would it be appropriate to write about the design and constraints of the DSN in the docstring of this function? I think it would be better to add a section about the DSN in doc.go.

[methane]

ja: このコメントでは実験的に、日本語と英語を両方記述しています。私は英文を書くのが苦手でAIに頼っていますが、元の日本語の文章にも価値があると考えているからです。
en: In this comment, I am writing both in Japanese and English experimentally. I rely on AI to write English because I am not good at it, but I believe that the original Japanese sentences also have value.

ja: 私はDSNをURIに近づけたいと思っています。 username と password は %-encode されるべきです。 tcp() は省略可能にするべきです。しかし、すでにusernameかpasswordに%が入っている場合に後方互換性を失うことになります。他にも後方互換性が失われるケースがあるかもしれませんが、まだ深く考えていません。
en: I want to make the DSN closer to a URI. The username and password should be %-encoded. The tcp() should be optional. However, this would break backward compatibility if there is already a % in the username or password. There may be other cases where backward compatibility is broken, but I haven't thought deeply about it yet.

ja: 過去のマイナーバージョンでも、より正しい動作をするために幾らかの後方互換性を犠牲にすることは許容してきました。API互換性を破壊しないのであれば、v2をリリースするよりも、少しの振る舞いの変更をユーザーに受け入れてもらう方が総合的にはいいと考えます。
en: In past minor versions, we have allowed some backward compatibility to be sacrificed for more correct behavior. If it does not break API compatibility, I think it is better overall to have users accept a small change in behavior rather than releasing v2.

ja: もう一つのアイデアは完全に新しいDSNを mysql+v1.11 のような新しいスキームと共に導入することですが、そのためには全てのユースケースを改めて考える必要があります。 #1736 は一つのオプションですが、本当にそれが良いのかまだ深く考えていません。
en: Another idea is to introduce a completely new DSN with a new scheme like mysql+v1.11, but that would require rethinking all the use cases. #1736 is one option, but I haven't thought deeply about whether it's really a good idea yet.