ClickHouse Go Driver: Client Go Hiệu Suất Cao

Kết Nối Ứng Dụng Go Với ClickHouse

ClickHouse Go Driver là một client database SQL viết bằng Golang cho ClickHouse, được publish dưới tên github.com/ClickHouse/clickhouse-go/v2. Nó cung cấp hai cách kết nối: một driver.Conn dành riêng cho ClickHouse, mở bằng clickhouse.Open, và một interface tương thích database/sql, mở bằng clickhouse.OpenDB. Cả hai hoạt động qua transport TCP native hoặc HTTP, và từ bản 2.3.0 trở lên client dùng thư viện ch-go ở tầng thấp hơn để encode và nén.

Năng Lực Cốt Lõi Và Tính Năng Nâng Cao

• ✓Hai interface kết nối trong cùng một package: clickhouse.Open trả về một driver.Conn dành riêng cho ClickHouse để encode column trực tiếp, còn clickhouse.OpenDB trả về một database/sql.DB chuẩn cho công cụ và ORM hiện có.
• ✓Cả hai interface đều hỗ trợ transport TCP native lẫn HTTP, nên cùng một client có thể chạy qua proxy như ChProxy hoặc load balancer HTTP mà không cần đổi API.
• ✓Marshal struct theo cả hai chiều — ScanStruct/Select map kết quả query vào struct, còn AppendStruct ghi một struct ngược lại thành một row.
• ✓Connection pool có thể cấu hình qua MaxOpenConns, MaxIdleConns, và ConnMaxLifetime, cùng với failover và load balancing trên danh sách host theo chiến lược in_order, round_robin, hoặc random.
• ✓Nén hỗ trợ LZ4, ZSTD, LZ4HC, GZIP, Deflate, và Brotli, với nén block native và nén web HTTP được xử lý như hai lớp riêng biệt, cấu hình rõ ràng.
• ✓Async insert qua helper WithAsync(), dùng được trên cả interface native lẫn database/sql, thay thế cho API AsyncInsert() đã deprecated.
• ✓Structured logging qua package log/slog của Go, hỗ trợ JWT authentication, và truy cập các tính năng giao thức qua Context như query ID, quota key, OpenTelemetry, và các sự kiện tiến trình thực thi.

Bắt Đầu Với Driver

Cài đặt bằng `go get github.com/ClickHouse/clickhouse-go/v2` — đó là bước cài đặt duy nhất mà README ghi lại; không có CLI riêng hay file config nào cần thiết lập trước. Phiên bản Go được hỗ trợ đi theo phiên bản của chính client: 2.0-2.2 cần Go 1.17/1.18, 2.3+ cần 1.18.4+/1.19, 2.29+ hỗ trợ Go 1.21 đến 1.24, và dải mới nhất được liệt kê, 2.41+, cần Go 1.24 hoặc 1.25, theo bảng tương thích trong README. Tài liệu đầy đủ nằm tại clickhouse.com/docs/en/integrations/go.

Ví Dụ Kết Nối Và Truy Vấn

Mở một kết nối native nghĩa là dựng một struct clickhouse.Options — địa chỉ, Auth (Database/Username/Password), và tuỳ chọn Settings, Compression, timeout — rồi gọi clickhouse.Open(&options) và conn.Ping(ctx) để xác nhận kết nối được: ```go conn, err := clickhouse.Open(&clickhouse.Options{ Addr: []string{"127.0.0.1:9000"}, Auth: clickhouse.Auth{ Database: "default", Username: "default", Password: "", }, }) if err != nil { return err } return conn.Ping(context.Background()) ``` Với database/sql, clickhouse.OpenDB(&options) trả về một *sql.DB mà bạn cấu hình theo cách thông thường, bằng SetMaxIdleConns, SetMaxOpenConns, và SetConnMaxLifetime. Một chuỗi DSN cũng dùng được — `clickhouse://user:pass@host1:9000,host2:9000/database?dial_timeout=200ms&read_timeout=30s` — và các tham số query như compress, secure, connection_open_strategy ánh xạ trực tiếp sang các field của Options. Ghi hàng loạt đi qua PrepareBatch ở interface native, hoặc theo mẫu begin→prepare→exec-trong-vòng-lặp→commit với database/sql.

Chọn Giữa Interface Native Và `database/sql`

Câu Hỏi Thường Gặp

Vấn đề ClickHouse Go Driver giải quyết

Mọi ứng dụng Go giao tiếp với ClickHouse đều phải chọn một giao thức truyền tải và một kiểu API trước khi viết query đầu tiên, và chọn sai sẽ trả giá bằng throughput thực tế hoặc buộc phải viết lại sau này. README giải quyết thẳng vấn đề này bằng bảng so sánh "Which interface should I use?" của riêng nó — một driver.Conn dành riêng cho ClickHouse để encode column trực tiếp, hoặc một driver tương thích database/sql cho công cụ sẵn có — thay vì chỉ cung cấp một driver SQL chung chung rồi để bạn tự phát hiện đánh đổi đó qua một benchmark sau này.

Trường hợp sử dụng tốt nhất

• •Xây dựng một service Go mới ghi vào hoặc query ClickHouse và muốn đường đi nhanh nhất — README khuyên dùng interface native driver.Conn với cách encode column trực tiếp khi bạn phân vân.
• •Thêm ClickHouse vào một codebase đã xây trên công cụ database/sql hoặc một ORM, qua clickhouse.OpenDB, mà không cần đưa thêm một API driver riêng thứ hai vào.
• •Stream bulk insert hoặc export ở định dạng gốc của server — QueryFormat/InsertFormat truyền thẳng CSV, JSONEachRow, hoặc Parquet mà driver không encode lại.
• •Kết nối qua một HTTP proxy hoặc load balancer như ChProxy, vì định dạng native có thể truyền qua transport HTTP cũng như TCP thô.
• •Chạy insert bất đồng bộ, không chặn, qua WithAsync() trong các pipeline ghi nhiều dữ liệu mà không cần từng insert được xác nhận trước khi tiếp tục.

Ai nên dùng — và ai nên bỏ qua

Hãy dùng ClickHouse Go Driver nếu bạn viết code Go mới cho ClickHouse và muốn truy cập trực tiếp các tính năng giao thức native — connection pool, failover, lựa chọn nén, và API driver.Conn — mà không đi qua database/sql. Dùng riêng interface database/sql, nhưng vẫn giữ cùng driver, nếu bạn gắn ClickHouse vào một codebase hoặc ORM dựa trên database/sql sẵn có và chấp nhận đánh đổi một phần throughput để lấy khả năng tương thích, theo đúng so sánh benchmark của dự án. Bỏ qua toàn bộ package nếu bạn cần một client ở ngôn ngữ khác ngoài Go.

Repo liên quan