chore: Async inserts docs and example updates by kavirajk · Pull Request #1690 · ClickHouse/clickhouse-go

kavirajk · 2025-10-17T11:49:33Z

Summary

Previously it was confusing (1) how to use async inserts (2) what kind of interfaces supports async inserts.

This PR address both. Changes

Deprecate WithStdAsync and prefer new WithAsync
Deprecate AsyncInsert() api and prefer new WithAsync
Add more examples for all possible cases
Update README

Checklist

Delete items not relevant to your PR:

Unit and integration tests covering the common scenarios were added
A human-readable description of the changes was provided to include in CHANGELOG
For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

Previously it was confusing (1) how to use async inserts (2) what kind of interfaces supports async inserts. This PR address both. Changes 1. Deprecate `WithStdAsync` and prefer new `WithAsync` 2. Deprecate `AsyncInsert()` api and prefer new `WithAsync` 3. Add more examples for all possible cases 4. Update README Signed-off-by: Kaviraj <[email protected]>

Signed-off-by: Kaviraj <[email protected]>

Copilot

Pull Request Overview

Deprecates legacy async insert APIs in favor of a new context-based WithAsync option and updates examples and README accordingly.

Introduces WithAsync() and deprecates WithStdAsync() and AsyncInsert()
Refactors examples/benchmarks to use Exec + WithAsync() instead of AsyncInsert()
Adds separate native/HTTP async insert examples and updates documentation

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/utils.go	Adjusts HTTP connection helpers to accept a string session identifier instead of *testing.T
lib/driver/driver.go	Marks AsyncInsert as deprecated in the driver interface
examples/std/main_test.go	Splits async insert test into native and HTTP variants
examples/std/async_native.go	Renames function and switches to WithAsync() usage
examples/std/async_http.go	Adds new HTTP async insert example using WithAsync()
examples/clickhouse_api/utils.go	Adds HTTP connection helper; import reordering
examples/clickhouse_api/main_test.go	Splits async insert test into native and HTTP variants
examples/clickhouse_api/async_native.go	Renames and migrates to Exec + WithAsync()
examples/clickhouse_api/async_http.go	Adds HTTP async insert example with session name
context.go	Adds WithAsync() and deprecates WithStdAsync()
conn_async_insert.go	Minor formatting (blank line)
clickhouse.go	Adds context-based async handling inside Exec; deprecates AsyncInsert method
benchmark/v2/write-async/main.go	Migrates benchmark to WithAsync() but retains a stale argument
README.md	Updates async insert documentation and deprecation notice

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-17T13:20:50Z

benchmark/v2/write-async/main.go

-		err := conn.AsyncInsert(ctx, fmt.Sprintf(`INSERT INTO benchmark_async VALUES (
+		err := conn.Exec(ctx, fmt.Sprintf(`INSERT INTO benchmark_async VALUES (
 			%d, '%s', [1, 2, 3, 4, 5, 6, 7, 8, 9], now()
 		)`, i, "Golang SQL database driver"), false)


The trailing false argument is now treated as a bind parameter to Exec, but the query has no placeholders; this will cause a parameter count mismatch or unintended binding. Remove the false argument and rely on WithAsync(true) for async wait semantics (or adjust WithAsync(false) if non-waiting behavior is desired).

Suggested change

)`, i, "Golang SQL database driver"), false)

)`, i, "Golang SQL database driver"))

Copilot · 2025-10-17T13:20:51Z

README.md

-HTTP protocol supports batching. It can be enabled by setting `async_insert` when using standard `Prepare` method.
-
-For more details please see [asynchronous inserts](https://clickhouse.com/docs/en/optimize/asynchronous-inserts#enabling-asynchronous-inserts) documentation.
+**NOTE**: The old `AsyncInsert()` api is deprecated and will be removed in future versions. We highly recommend to use `WithAsync()` api for all the Async Insert use cases.


Correct acronym capitalization: change 'api' to 'API' in both occurrences.

Suggested change

**NOTE**: The old `AsyncInsert()` api is deprecated and will be removed in future versions. We highly recommend to use `WithAsync()` api for all the Async Insert use cases.

**NOTE**: The old `AsyncInsert()` API is deprecated and will be removed in future versions. We highly recommend to use `WithAsync()` API for all the Async Insert use cases.

Copilot · 2025-10-17T13:20:51Z

examples/std/async_http.go

+	const ddl = `
+		CREATE TABLE example (
+			  Col1 UInt64
+			, Col2 String
+			, Col3 Array(UInt8)
+			, Col4 DateTime
+		) ENGINE = Memory
+		`
+	if _, err := conn.Exec(ddl); err != nil {
+		return err
+	}
+	ctx := clickhouse.Context(context.Background(), clickhouse.WithAsync(false))
+	{
+		for i := 0; i < 100; i++ {
+			_, err := conn.ExecContext(ctx, `INSERT INTO example VALUES (
+				?, ?, ?, now()
+			)`, i, "Golang SQL database driver", []uint8{1, 2, 3, 4, 5, 6, 7, 8, 9})
+			if err != nil {
+				return err
+			}
+		}
+	}


[nitpick] This block duplicates the logic in async_native.go (table DDL + insert loop); consider extracting a shared helper (e.g., createAndFillExample(ctx, conn)) to reduce repetition and ease future changes.

Signed-off-by: Kaviraj <[email protected]>

vincentbernat · 2025-11-24T21:14:17Z

Shouldn't we use clickhouse.WithAsync(true)?

My bad, the boolean is for whatever to wait for asynchronous insert to return. So, false means return immediatly and true means wait for the async insertion to be done.

kavirajk marked this pull request as ready for review October 17, 2025 11:50

fix build failure on async test on examples

68e798f

Signed-off-by: Kaviraj <[email protected]>

mshustov requested review from Copilot and jkaflik and removed request for Copilot October 17, 2025 13:19

Copilot AI reviewed Oct 17, 2025

View reviewed changes

add more examples to show case async insert with prepared statement

96e68f4

Signed-off-by: Kaviraj <[email protected]>

kavirajk requested a review from SpencerTorres October 17, 2025 20:12

SpencerTorres approved these changes Oct 22, 2025

View reviewed changes

SpencerTorres merged commit 1d64d6c into main Oct 22, 2025
14 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: Async inserts docs and example updates#1690

chore: Async inserts docs and example updates#1690
SpencerTorres merged 3 commits intomainfrom
kavirajk/async-fixes-and-docs-update

kavirajk commented Oct 17, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 17, 2025

Uh oh!

Copilot AI Oct 17, 2025

Uh oh!

Copilot AI Oct 17, 2025

Uh oh!

Uh oh!

vincentbernat commented Nov 24, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	)`, i, "Golang SQL database driver"), false)
	)`, i, "Golang SQL database driver"))

	NOTE: The old `AsyncInsert()` api is deprecated and will be removed in future versions. We highly recommend to use `WithAsync()` api for all the Async Insert use cases.
	NOTE: The old `AsyncInsert()` API is deprecated and will be removed in future versions. We highly recommend to use `WithAsync()` API for all the Async Insert use cases.

Conversation

kavirajk commented Oct 17, 2025

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vincentbernat commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vincentbernat commented Nov 24, 2025 •

edited

Loading