[polyglotAI-bot]

Summary

Fixes #686 (solution 1, as the maintainer chose).

ClickHouseDataSource.OpenConnectionAsync(CancellationToken cancellationToken) had no default value for its token. So a call with no argument, await dataSource.OpenConnectionAsync(), did not bind to it. It bound to the base DbDataSource.OpenConnectionAsync(CancellationToken = default), which is typed ValueTask<DbConnection>. The documented ADO.NET examples in docs/http.mdx then call connection.CreateCommand("..."), which does not exist on DbConnection, and fail with CS1501. The fix declares the token as CancellationToken cancellationToken = default, as IClickHouseDataSource.OpenConnectionAsync already does. The no-argument call now binds to the ClickHouseDataSource method and is typed Task<ClickHouseConnection>.

Changes

• ClickHouse.Driver/ADO/ClickHouseDataSource.cs: add = default to the token of OpenConnectionAsync.
• PublicAPI/PublicAPI.Unshipped.txt and PublicAPI/net8.0/PublicAPI.Shipped.txt: update the signature line (the only two files that list it).
• changelog.d/686-datasource-openconnectionasync.fixes.md: changelog fragment.
• No docs change: the docs/http.mdx snippets are now correct as written.

Test

DataSourceTests.OpenConnectionAsync_WithoutCancellationToken_ReturnsOpenClickHouseConnection opens a connection with the no-argument call against the server. It assigns the result to ClickHouseConnection, checks that the state is Open, and runs CreateCommand("SELECT 1"). Without the fix the test project does not compile (CS0266: cannot convert DbConnection to ClickHouseConnection). With the fix it passes.

Also checked by hand against a 26.9 server: the three docs/http.mdx snippets from the issue (lines 1296, 1350 and 1556) now compile and run. These calls keep their previous types: an explicit token (Task<ClickHouseConnection>), a call through IClickHouseDataSource (Task<IClickHouseConnection>), and a call through a DbDataSource-typed variable (ValueTask<DbConnection>).

Compatibility

• Binary compatible: the method signature does not change. Only the default-value metadata is new. Assemblies that are already compiled are not affected.
• Source: after a recompile, a no-argument call on a ClickHouseDataSource-typed variable is typed Task<ClickHouseConnection>, not ValueTask<DbConnection>. Code that uses var/await keeps compiling. Code that stores the unawaited call in an explicit ValueTask<DbConnection>, or calls .AsTask() / .Preserve() on it, stops compiling. Calls through DbDataSource, through IClickHouseDataSource, and method-group conversions do not change.

Checklist

• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The source-breaking return-type change needs user-facing migration guidance beyond the PR description.

1 open finding

• Document ClickHouseDataSource return-type compatibility change · New

What changed in this PR

Fixes #686 in the HTTP client's ADO.NET API so awaiting ClickHouseDataSource.OpenConnectionAsync() returns ClickHouseConnection.

Changes:

• Makes the cancellation token optional.
• Updates API records and adds a regression test.
• Adds a changelog fragment.

File	Description
ClickHouse.Driver/​PublicAPI/​PublicAPI.Unshipped.txt	Records the optional token.
ClickHouse.Driver/​PublicAPI/​net8.0/​PublicAPI.Shipped.txt	Updates the framework-specific signature.
ClickHouse.Driver/​ADO/​ClickHouseDataSource.cs	Defaults the cancellation token.
ClickHouse.Driver.Tests/​ADO/​DataSourceTests.cs	Tests the no-argument call and command execution.
changelog.d/​686-datasource-openconnectionasync.fixes.md	Announces the fix.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[polyglotAI-bot]

Checked on this branch. The source change is real: ValueTask<DbConnection> t = ds.OpenConnectionAsync(); now fails with CS0029, and .AsTask() / .Preserve() on the call fail with CS1061. ((DbDataSource)ds).OpenConnectionAsync() still compiles and returns ValueTask<DbConnection>. DbConnection c = await ds.OpenConnectionAsync(); also still compiles.

• Changelog: done in ac7929b. The 686 fragment now has a sub-bullet that names the new return type, the code that stops compiling, and the two ways to keep it compiling. changelog.cs --check passes.
• docs/http.mdx: no change. The docs page describes the current API, and the #ado-net-datasource examples are already correct for it. The page has no per-version compatibility notes; its only migration guide is for the ClickHouse.Client → ClickHouse.Driver rename. CHANGELOG.md is where this repo records source breaks for an upgrade (for example the Logger → LoggerFactory entry). I left this thread open so a maintainer can decide whether they also want a docs note.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!