Documentation
¶
Overview ¶
Package chclient is a HTTP-based ClickHouse client for runtime services per ADR-0026 M2.5b. Modelled on play.Client (the SQL-playground HTTP client) plus the card_anchor integration test's minimal InsertArrow path. Provides:
- Ping for skip-if-unavailable test gating.
- Exec for DDL and side-effect SQL.
- Query for SELECT with caller-managed body decoding.
- InsertArrow for Arrow IPC bulk writes via FORMAT Arrow.
CGO-free; HTTP port 8123 by convention. The project's localhost CH reference is in memory: reference_clickhouse_localhost_defaults.
Index ¶
- Variables
- type Client
- func (inst *Client) Exec(ctx context.Context, sql string) (err error)
- func (inst *Client) InsertArrow(ctx context.Context, table string, records []arrow.RecordBatch) (err error)
- func (inst *Client) Ping(ctx context.Context) (err error)
- func (inst *Client) Query(ctx context.Context, sql string) (body io.ReadCloser, err error)
- func (inst *Client) QueryParams(ctx context.Context, sql string, params map[string]string) (body io.ReadCloser, err error)
- type Config
Constants ¶
This section is empty.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMBlocked, WASMJS: packageprops.WASMBlocked, WASMFreestanding: packageprops.WASMBlocked, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps net/http with the small set of CH-specific shaping the runtime needs (headers, FORMAT Arrow URL building). Goroutine-safe.
func (*Client) Exec ¶
Exec POSTs sql to the base URL and discards the response body. Used for DDL and any SQL that does not return rows.
A failure after the status line is discarded with the body ¶
The shared postSQL helper checks the HTTP status, so anything ClickHouse rejects before it starts answering — a syntax error, an unknown identifier, a permission refusal — comes back as an error carrying the server's own diagnostic. That is the common case and it is covered.
What is not covered: ClickHouse can answer 200 and fail part way through producing the response, in which case the exception text lands in the body this function throws away, and Exec returns nil. The same failure class is documented for github.com/stergiotis/boxer/public/keelson/data/storeexec.Executor.QueryArrow, where it surfaces instead as an Arrow decode error mid-iteration.
Whether it is reachable for the statements Exec is actually given — DDL and other row-less SQL — has not been established, which is why nothing here tries to catch it: a check for a failure nobody has reproduced would be a permanent cost against a hypothetical. If it needs closing, the pieces exist. github.com/stergiotis/boxer/public/db/clickhouse/chhttp knows both the `X-ClickHouse-Exception-Code` header and the `Code: N. DB::Exception: …` body shape, and `wait_end_of_query=1` makes the case impossible at the cost of buffering the whole reply server-side.
func (*Client) InsertArrow ¶
func (inst *Client) InsertArrow(ctx context.Context, table string, records []arrow.RecordBatch) (err error)
InsertArrow POSTs Arrow IPC records to INSERT INTO {table} FORMAT Arrow. The records slice may be empty (no-op). Caller is responsible for releasing the records after the call returns.
func (*Client) Ping ¶
Ping returns nil when the CH server answers HTTP /ping with 200. Tests use this for skip-if-unavailable logic so the suite is green without a running server.
func (*Client) Query ¶
Query POSTs sql and returns the response body for caller consumption. Caller MUST close. Format is whatever the SQL FORMAT clause specifies.
func (*Client) QueryParams ¶ added in v0.0.15
func (inst *Client) QueryParams(ctx context.Context, sql string, params map[string]string) (body io.ReadCloser, err error)
QueryParams is Query with server-side parameter binding: each params entry rides the ClickHouse HTTP `param_<name>` URL channel, where the server substitutes it into the matching `{<name>:Type}` placeholder in sql. The SQL text itself stays constant, so values — including user-supplied ones — are never concatenated into the statement.
Keys are the bare placeholder names: params["q"] binds `{q:String}`. Values are the raw ClickHouse text form for the placeholder's declared type (`[1,2,3]` for an Array(UInt64), an unquoted string for a String). A nil or empty map behaves exactly like Query.
Caller MUST close the returned body.
type Config ¶
Config carries the connection URL + credentials. URL is the base HTTP endpoint (e.g. "http://localhost:8123/"); operations append query strings as needed.
func ConfigFromEnv ¶ added in v0.0.20
func ConfigFromEnv() (c Config)
ConfigFromEnv layers the CLICKHOUSE_* registry entries (ADR-0009) over Defaults. The endpoint is CLICKHOUSE_ENDPOINT, falling back to CLICKHOUSE_URL and then to the Defaults URL; credentials come from CLICKHOUSE_USER / CLICKHOUSE_PASSWORD. An entry that is unset or empty leaves the corresponding default in place, so the zero-configuration case stays exactly what Defaults describes.
The two endpoint spellings exist because CLICKHOUSE_URL predates CLICKHOUSE_ENDPOINT and both remain declared; this is the one place that decides which wins. Either may carry a trailing slash — Ping trims it and the query paths tolerate its absence.
Not a live re-read: the registry resolves each entry once and caches it (a CLI flag bound to the same Spec writes through that cache), so mutating the environment after the first resolution has no effect. Callers wanting a different server pass it in the environment before start, or build a Config themselves.
Callers that must not read the environment (fixed coordinates, or a test pinning a server) keep using Defaults.
Source Files