docs(gosqlx): refresh pkg.go.dev docs for ParseTree and extend examples

[ajitpratap0]

Summary

• pkg/gosqlx/doc.go: document ParseTree (v1.15.0), functional options, sentinel errors and Tree helpers; list all 8 dialects; drop stale v1.6.0 feature heading.
• Root doc.go: add recommended ParseTree usage, 8 dialects, lint rules updated to 30 (L001-L030).
• pkg/gosqlx/example_test.go: add runnable ExampleParseTree, ExampleParseTree_dialect, ExampleTree_Format, ExampleTree_Functions.
• CHANGELOG.md intentionally not edited (next release prepared in another session): suggested Unreleased entry is 'Docs: pkg.go.dev docs and examples for ParseTree'.

Test Plan

• go test ./pkg/gosqlx -run Example (Output checks pass)
• go doc ./pkg/gosqlx shows ParseTree
• task check passes

Breaking Changes

None (documentation and tests only).

Closes #671
Part of #634

🤖 Generated with Claude Code

https://claude.ai/code/session_01RkzVu3JY9Y6BRWfjesWts9

[vercel]

Deployment failed for project gosqlx-website with the following error:

Resource is limited - try again in 1 day (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/coolajitpratapsingh0-9932s-projects?upgradeToPro=build-rate-limit

[github-actions]

Claude finished @ajitpratap0's task in 26s —— View job

---

Review of PR #713: pkg.go.dev docs and examples for ParseTree

Verdict: looks good. This is a docs and examples change with no production code touched, and I have a few small suggestions. I couldn't run go test here because the command needed approval, so I checked the new docs and examples against the source by reading it.

• Read the diff
• Checked the documented API against pkg/gosqlx (tree.go, options.go, errors.go)

Checked against the source

• ParseTree options exist: WithDialect, WithStrict, WithTimeout and WithRecovery are in options.go.
• The four sentinel errors exist in errors.go: ErrSyntax, ErrTokenize, ErrTimeout and ErrUnsupportedDialect.
• The Tree methods used in the docs exist in tree.go: Walk, Functions, Statements, Rewrite, Clone, Raw, Tables, Columns, Format and Release.
• WithUppercaseKeywords(bool) exists as a FormatOption, so ExampleTree_Format compiles.
• Go example naming is valid. ExampleParseTree_dialect uses a lowercase suffix, and ExampleTree_Format and ExampleTree_Functions match real methods, so go vet should be happy.
• The root doc.go lint count and dialect list match CLAUDE.md (30 rules, 8 dialects).

Suggestions

1. pkg/gosqlx/doc.go Quick Start comments: // [users], // [id name active] and the formatted-SQL line are not verified by any example. ExampleParseTree only asserts Tables(). Please confirm that Columns() really returns [id name active], in that order and without deduplication. If you're unsure, drop the literal output. Otherwise it can go stale without any test failing.
2. Tree helper list: it omits the typed walkers (WalkSelects, WalkJoins, WalkCTEs and so on) and SQL(). WithMaxBytes is also missing from the options list. A short mention would make the docs match the API.
3. ExampleParseTree_dialect: the name suggests a dialect demo, but the dialect case only prints <nil>. It would be more convincing to show a dialect-specific construct that parses under one dialect, or to show errors.Is(err, gosqlx.ErrUnsupportedDialect) for a bogus dialect. The ErrSyntax check also depends on SELECT FROM WHERE always failing to parse. That should hold, but it is fragile if the parser ever becomes more lenient.
4. ExampleTree_Format output: the expected output is SELECT id\nFROM users. This ties the example to the formatter's current line-breaking behavior. That's acceptable, but formatter changes will need to update it.
5. Version wording: "v1.15.0+" appears in two places. Make sure it matches the release this will ship in, since CLAUDE.md currently lists v1.14.0.
6. CHANGELOG: I understand it is left out deliberately. Add the suggested Unreleased entry when the other session's release prep lands.

Other review areas

• Security and performance: none, since the change is docs and tests only.
• Test coverage: four new runnable examples with // Output: checks. All use defer tree.Release(), which follows the repo's pooling rules.

Please run go test ./pkg/gosqlx -run Example and task check to confirm the examples pass before merging.
· branch docs/pkgsite-doc-comments

[ajitpratap0]

Fixed: the Quick Start comment in pkg/gosqlx/doc.go now reads // [active id name], matching the sorted, deduplicated output of Columns(). gofmt, vet and race tests for pkg/gosqlx pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RkzVu3JY9Y6BRWfjesWts9

[vercel]

Deployment failed for project gosqlx-website with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/coolajitpratapsingh0-9932s-projects?upgradeToPro=build-rate-limit

[github-actions]

Claude finished @ajitpratap0's task in 14s —— View job

---

Review of PR #713: pkg.go.dev docs and examples for ParseTree

Verdict: looks good to merge. This change only touches docs and example tests, so it carries no production risk. I read the diff (git diff origin/main...HEAD) but did not run go test here.

• Read the diff
• Checked the follow-up fix to the Quick Start comment

What I checked

• The Columns() comment now reads // [active id name], which matches the sorted, deduplicated output you described. That resolves the main concern from the earlier review.
• The root doc.go updates (8 dialects, lint rules L001-L030) match CLAUDE.md.
• All four new examples use defer tree.Release(), which follows the repo's pooling rules.
• The example names are valid for go vet. ExampleParseTree_dialect has a lowercase suffix, and ExampleTree_Format and ExampleTree_Functions match real methods.

Remaining suggestions (non-blocking)

1. ExampleParseTree_dialect: the name promises a dialect demo, but the dialect case only prints postgresql error: <nil>. That shows very little. A better demo would check errors.Is(err, gosqlx.ErrUnsupportedDialect) with a bogus dialect, or parse a dialect-specific construct. The ErrSyntax check also relies on SELECT FROM WHERE always failing, so it would break if the parser became more lenient.
2. Doc coverage:
   • WithMaxBytes is missing from the options list.
   • The typed walkers (WalkSelects, WalkJoins and similar) and SQL() are missing from the Tree helper list.
   • The tree.Format() comment line in Quick Start has no example backing it. ExampleTree_Format covers it only partly.
3. ExampleTree_Format output: it asserts SELECT id\nFROM users, which ties the example to the formatter's current line-breaking. This is acceptable, but formatter changes will need to update it.
4. Version wording: "v1.15.0+" appears in two places. Confirm it matches the release this ships in, since CLAUDE.md still says v1.14.0.
5. CHANGELOG: leaving it out is fine. Remember to add the suggested Unreleased entry when the other release prep lands.

Other areas

• Security and performance: no concerns.
• Test coverage: the four new examples have // Output: checks. Please confirm go test ./pkg/gosqlx -run Example passes in CI.
  · branch docs/pkgsite-doc-comments

[ajitpratap0]

Fixed: pkg/gosqlx/doc.go now says 30 linting rules (L001-L030) in both places (docs list and the package tree), matching root doc.go. gofmt, go vet and go test ./pkg/gosqlx pass.

[github-actions]

Claude finished @ajitpratap0's task in 14s —— View job

---

Review of PR #713: pkg.go.dev docs and examples for ParseTree

Verdict: looks good to merge. The change only touches docs and example tests. I read the diff (git diff origin/main...HEAD) but did not run go test here.

• Read the diff
• Checked the Columns() comment fix

What I checked

• The Quick Start comment now reads // [active id name], which matches the sorted, deduplicated output you described. That resolves the earlier concern.
• Root doc.go and pkg/gosqlx/doc.go report 8 dialects and 30 lint rules (L001-L030), matching CLAUDE.md.
• All four new examples use defer tree.Release(), which follows the repo's pooling rules.
• The example names are valid for go vet: ExampleParseTree_dialect has a lowercase suffix, and ExampleTree_Format and ExampleTree_Functions match real methods.

Suggestions (non-blocking)

1. ExampleParseTree_dialect (pkg/gosqlx/example_test.go):
   • The dialect case only prints postgresql error: <nil>, which shows little.
   • Checking errors.Is(err, gosqlx.ErrUnsupportedDialect) with a bogus dialect would be a stronger demo. A dialect-specific construct would also work.
   • The ErrSyntax check depends on SELECT FROM WHERE always failing. That would break if the parser became more lenient.
2. Doc coverage (pkg/gosqlx/doc.go):
   • WithMaxBytes is missing from the options list.
   • The typed walkers (WalkSelects, WalkJoins and similar) and SQL() are missing from the Tree helper list.
   • The tree.Format() line in Quick Start has no example backing it. ExampleTree_Format only partly covers it.
3. ExampleTree_Format output: it asserts SELECT id\nFROM users, which ties the example to the formatter's current line-breaking. That is acceptable, but formatter changes will need to update it.
4. Version wording: "v1.15.0+" appears in two places. Confirm it matches the release this ships in, since CLAUDE.md still lists v1.14.0.
5. CHANGELOG: leaving it out is fine. Add the suggested Unreleased entry when the other release prep lands.

Other areas

• Security and performance: no concerns.
• Test coverage: the four new examples have // Output: checks. Please confirm go test ./pkg/gosqlx -run Example passes in CI.
  · branch docs/pkgsite-doc-comments

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
gosqlx-website	Ready	Preview	Oct 14, 2026 7:43pm UTC

[github-actions]

Claude finished @ajitpratap0's task in 18s —— View job

---

Review of PR #713: pkg.go.dev docs and examples for ParseTree

Verdict: looks good to merge. This change touches only docs and example tests. I read the diff (git diff origin/main...HEAD) but did not run go test.

• Read the diff
• Checked the docs and examples against earlier feedback

What I checked

• The Quick Start comments now read // [users] and // [active id name]. Earlier feedback about the Columns() output is addressed.
• Both doc.go files now say 8 dialects and 30 lint rules (L001-L030), matching CLAUDE.md.
• All four new examples use defer tree.Release(), which follows the repo's pooling rules.
• The example names are valid for go vet. ExampleParseTree_dialect has a lowercase suffix. ExampleTree_Format and ExampleTree_Functions match real methods.
• The errors import is used, and the // Output: blocks are well-formed.

Suggestions (non-blocking)

1. ExampleParseTree_dialect (pkg/gosqlx/example_test.go, around line 713):
   • The dialect case only prints postgresql error: <nil>, which shows little.
   • A stronger demo would call errors.Is(err, gosqlx.ErrUnsupportedDialect) with a bogus dialect, or parse a dialect-specific construct.
   • The ErrSyntax check depends on SELECT FROM WHERE always failing. That would break if the parser became more lenient.
2. Doc coverage (pkg/gosqlx/doc.go):
   • WithMaxBytes is missing from the options list.
   • The typed walkers (WalkSelects, WalkJoins and similar) and SQL() are missing from the Tree helper list.
3. ExampleTree_Format: the expected output ties the example to the formatter's current line-breaking. Formatter changes will need to update it.
4. Version wording: "v1.15.0+" appears in two places. Confirm it matches the release this ships in, since CLAUDE.md still says v1.14.0.
5. CHANGELOG: leaving it out is fine. Add the suggested Unreleased entry when the other release prep lands.

Other areas

• Security and performance: no concerns.
• Test coverage: the four new examples assert their output. Please confirm go test ./pkg/gosqlx -run Example passes in CI.
  · branch docs/pkgsite-doc-comments