Documentation
¶
Overview ¶
Package clickhouse is a database/sql driver for ClickHouse, which takes a statement over its HTTP interface. It registers the one name "clickhouse", and takes a DSN of the form clickhouse://user:password@host:8123/database (D177).
db, err := sql.Open("clickhouse", "clickhouse://default:secret@localhost:8123/default")
The driver sends a statement with POST /, and reads the answer in the format JSONCompactEachRowWithNamesAndTypes, one row at a time, with the settings that make each value exact (D176). It binds each argument as a typed parameter of the server, such as {p1:Int64} with param_p1 in the query string (D176). An error after some rows comes from the marker that the server writes in the stream, and wraps dbimp.ErrIncomplete (D107 and D176). The server runs a query on when its client leaves, so the driver names each query and sends KILL QUERY when the context ends and when the caller closes the rows early (D176). The server has no transaction, so BeginTx fails with dbimp.ErrNotSupported (D177). docs/CLICKHOUSE.md holds what the driver knows about the server.
Index ¶
Constants ¶
const Name = "clickhouse"
Name is the name that the driver registers with database/sql, and the scheme of its DSN.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Host is the host of the server.
Host string
// Port is the port of the HTTP interface, 8123 by default and 8443 with
// TLS.
Port int
// TLS is true to speak HTTPS.
TLS bool
// User and Password are the credentials, which the driver sends with
// basic authentication, if either one is not empty. With neither, the
// server uses its user default.
User string
Password string
// Database is the database of each statement, and empty to leave the
// choice to the server.
Database string
}
Config is the configuration of a connector, which the DSN holds. The caller owns it (D7).
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector opens connections to one server. It owns its transport, and every connection shares it. A caller can build one from a Config and open it with sql.OpenDB.
func NewConnector ¶
NewConnector returns a Connector for cfg. The connector keeps a copy of cfg, and fills each field that is zero with its default.
type Driver ¶
type Driver struct{}
Driver is the database/sql driver for ClickHouse.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// Code is the code of the error, such as 60, from the header
// X-ClickHouse-Exception-Code or from the text. It is 0 when neither
// holds one.
Code int
// Name is the name of the code, such as UNKNOWN_TABLE, and empty when the
// text has none.
Name string
// Message is the text of the error without the code, the name and the
// version.
Message string
// contains filtered or unexported fields
}
Error is an error that ClickHouse reported. The text of each error has the form "Code: 60. DB::Exception: Table t does not exist. (UNKNOWN_TABLE) (version 26.9.2.8 (official build))" (measured). An error that comes before the first byte of the body has the status of HTTP that follows its code: 400 for a syntax error, 404 for an unknown table, database or setting, 401 or 403 for a wrong password, 500 for a type error, and 501 for a feature that is not there. An error after some rows has HTTP 200, or HTTP 500 on 26.9, and the text comes after the rows (measured).
type Option ¶
Option sets an option of one statement (D109). An option comes from the DSN, then from the context through WithOptions, then from an argument of the statement, and a later one wins.
func WithDatabase ¶
WithDatabase sets the database of one statement, as the path of the DSN does, with the query key database.
func WithParameter ¶
WithParameter sets a setting of the server for one statement by its name, such as "max_threads". The value is written with fmt.Sprint, and a bool is 1 or 0. A name that the driver sets itself, such as "query_id", takes this value in its place. So a caller who replaces "default_format" breaks the reading of the answer, and a caller who replaces "query_id" names the query that the driver cancels. A name that the server does not know fails the statement with the code 115 (measured). WithParameter(name, nil) writes no value, and fails the statement with dbimp.ErrInvalidValue.
func WithReadonly ¶
WithReadonly asks that the statement write nothing, with the setting readonly set to 1 (D109). The server then refuses a write with the code 164, and a change of a setting in the text of the statement, such as a SETTINGS clause. It still accepts the settings in the query string, which are the settings of the driver (measured).
func WithTimeout ¶
WithTimeout sets the time that the server gives the statement, as the setting max_execution_time, which counts seconds with a fraction. The server stops a statement that runs longer with the code 159, which is HTTP 408 on 26.9, and an error after the rows on 25.3 and 25.8 (measured). Zero sends no timeout, and the server uses its own. The DSN has no key for it, because a user who cannot change the setting gets an error (D176).
Source Files