Help us shape the future of Go! Take the 2026 Go Developer Survey

clickhouse

package
v1.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2026 License: MIT Imports: 39 Imported by: 0

Documentation

Overview

Package clickhouse is the ClickHouse driver of sqlconnect. It talks HTTPS to ClickHouse through the rudderlabs clickhouse-go fork.

Index

Constants

View Source 
const DatabaseType = "clickhouse"

DatabaseType is the registry key of the ClickHouse driver.

View Source 
const DefaultPort = 8443

DefaultPort is the HTTPS port used when the account omits port.

Variables

This section is empty.

Functions

func GoquDialectOptions 

func GoquDialectOptions() *sqlgen.SQLDialectOptions

GoquDialectOptions returns the Goqu options of the ClickHouse dialect. Goqu writes identifier text between quote runes without escaping it, so the dialect validates every identifier node before rendering (see walkIdentifiers).

func GoquExpressions 

func GoquExpressions() *base.Expressions

GoquExpressions renders TimestampAdd and DateAdd with dateAdd. The base dialect has already checked the unit and converted weeks to days.

Types

type Config 

type Config struct {
	Host       string `json:"host"`
	Port       int    `json:"port,omitempty"`
	Database   string `json:"database"`
	User       string `json:"user"`
	Password   string `json:"password"`
	Secure     *bool  `json:"secure,omitempty"`
	SkipVerify bool   `json:"skipVerify,omitempty"`
}

Config is the ClickHouse account configuration.

func ParseConfig 

func ParseConfig(raw json.RawMessage) (Config, error)

ParseConfig validates an account config. Only the installed dial policy can admit secure=false; without a policy, plain HTTP is refused.

func (Config) GoString 

func (c Config) GoString() string

GoString redacts the password, so %#v never prints it.

func (Config) PortOrDefault 

func (c Config) PortOrDefault() int

PortOrDefault maps an omitted port to DefaultPort, like the account schema default.

func (Config) String 

func (c Config) String() string

String redacts the password, so %v and %+v never print it.

type DB 

type DB struct {
	*base.DB
	// contains filtered or unexported fields
}

DB is the ClickHouse client.

func NewDB 

func NewDB(configJSON json.RawMessage) (*DB, error)

NewDB parses the account config and opens a lazy pool. It sends no request. Without an explicit dial policy, the fixed refused address set still applies.

func (*DB) AwaitTable 

func (db *DB) AwaitTable(ctx context.Context, exec sqlconnect.QueryExecutor, ref sqlconnect.RelationRef, wantUUID string, p sqlconnect.VisibilityPolicy) (string, error)

AwaitTable returns the table's UUID once the table is visible, and with a non-empty wantUUID once it has that UUID.

func (*DB) AwaitTableAbsent 

func (db *DB) AwaitTableAbsent(ctx context.Context, exec sqlconnect.QueryExecutor, ref sqlconnect.RelationRef, p sqlconnect.VisibilityPolicy) error

AwaitTableAbsent returns once the name resolves to no table.

func (*DB) Begin 

func (db *DB) Begin() (*sql.Tx, error)

Begin is not supported: ClickHouse has no transactions on this path.

func (*DB) BeginTx 

func (db *DB) BeginTx(context.Context, *sql.TxOptions) (*sql.Tx, error)

BeginTx is not supported: ClickHouse has no transactions on this path.

func (*DB) ClassifyError 

func (db *DB) ClassifyError(err error) sqlconnect.ErrorInfo

ClassifyError implements sqlconnect.ErrorClassifier.

func (*DB) CountTableRows 

func (db *DB) CountTableRows(ctx context.Context, table sqlconnect.RelationRef) (int, error)

CountTableRows counts the rows of a table. A count above the platform int returns CH_COUNT_OVERFLOW.

func (*DB) CreateSchema 

func (db *DB) CreateSchema(ctx context.Context, schema sqlconnect.SchemaRef) error

CreateSchema creates a database. The connector never calls it; it serves the shared test suite.

func (*DB) CreateTableForQueryWithOptions 

func (db *DB) CreateTableForQueryWithOptions(ctx context.Context, ex sqlconnect.QueryExecutor, ref sqlconnect.RelationRef, query string, o sqlconnect.MaterializationOptions) (string, error)

CreateTableForQueryWithOptions creates an empty MergeTree table for query on ex, waits until it is visible and returns its UUID. It runs no INSERT.

func (*DB) CreateTableFromQuery 

func (db *DB) CreateTableFromQuery(ctx context.Context, table sqlconnect.RelationRef, query string) error

CreateTableFromQuery overrides the base CTAS, which names no engine. It runs on one pinned connection with zero options.

func (*DB) CreateTableFromQueryWithOptions 

func (db *DB) CreateTableFromQueryWithOptions(ctx context.Context, ex sqlconnect.QueryExecutor, ref sqlconnect.RelationRef, query string, o sqlconnect.MaterializationOptions) (string, error)

CreateTableFromQueryWithOptions creates the table, waits until it is visible, then fills it. A failed INSERT leaves the table for the caller.

func (*DB) CreateTestTable 

func (db *DB) CreateTestTable(ctx context.Context, table sqlconnect.RelationRef) error

CreateTestTable creates the shared suite's test table if it is absent.

func (*DB) CurrentCatalog 

func (db *DB) CurrentCatalog(context.Context) (sqlconnect.CatalogRef, error)

CurrentCatalog is not supported: ClickHouse has no catalogs. It runs no SQL.

func (*DB) DropSchema 

func (db *DB) DropSchema(ctx context.Context, schema sqlconnect.SchemaRef) error

DropSchema drops a database now. A missing database returns CH_OBJECT_NOT_FOUND (server code 81).

func (*DB) DropTable 

func (db *DB) DropTable(ctx context.Context, ref sqlconnect.RelationRef) error

DropTable drops the table now if it exists.

func (*DB) GetRowCountForQuery 

func (db *DB) GetRowCountForQuery(ctx context.Context, query string, params ...any) (int, error)

GetRowCountForQuery runs the caller's count query on the pool and returns its single value. A count above the platform int returns CH_COUNT_OVERFLOW.

func (*DB) InsertFromQueryWithOptions 

func (db *DB) InsertFromQueryWithOptions(ctx context.Context, ex sqlconnect.QueryExecutor, ref sqlconnect.RelationRef, query string, o sqlconnect.MaterializationOptions) error

InsertFromQueryWithOptions fills a table that CreateTableForQueryWithOptions created with the same options. With explicit Columns it first checks the query projection through DESCRIBE, so a mismatch writes nothing.

func (*DB) JSONRowMapper 

func (db *DB) JSONRowMapper() sqlconnect.RowMapper[map[string]any]

JSONRowMapper replaces the base mapper, whose value callback cannot report an error. It returns an error instead of a partial row.

func (*DB) ListCatalogs 

func (db *DB) ListCatalogs(context.Context) ([]sqlconnect.CatalogRef, error)

ListCatalogs is not supported: ClickHouse has no catalogs. It runs no SQL.

func (*DB) ListColumns 

func (db *DB) ListColumns(ctx context.Context, relation sqlconnect.RelationRef) ([]sqlconnect.ColumnRef, error)

ListColumns lists the columns in declaration order. RawType keeps the server's type text byte for byte. Zero rows mean the table is absent or invisible: CH_OBJECT_NOT_FOUND.

func (*DB) ListColumnsForSqlQuery 

func (db *DB) ListColumnsForSqlQuery(ctx context.Context, q string) ([]sqlconnect.ColumnRef, error)

ListColumnsForSqlQuery returns the result columns of a SQL query without running it. A zero-row HTTP answer carries no column metadata, so the query goes through DESCRIBE. Callers that require audience policy checks must opt in with clickhousequery.CheckAudienceSQL before calling this method.

func (*DB) ListSchemas 

func (db *DB) ListSchemas(ctx context.Context, opts ...sqlconnect.Option) ([]sqlconnect.SchemaRef, error)

ListSchemas lists the databases other than the system ones. A non-empty catalog filter returns an empty result and runs no SQL.

func (*DB) ListTables 

func (db *DB) ListTables(ctx context.Context, schema sqlconnect.SchemaRef, opts ...sqlconnect.Option) ([]sqlconnect.RelationRef, error)

ListTables lists the tables and views of one database whose names start with the prefix. '%' and '_' in the prefix are literal. A non-empty catalog filter returns an empty result and runs no SQL.

func (*DB) MoveTable 

func (db *DB) MoveTable(ctx context.Context, oldRef, newRef sqlconnect.RelationRef) error

MoveTable overrides the base move. It runs on one pinned connection with zero options.

func (*DB) MoveTableWithOptions 

func (db *DB) MoveTableWithOptions(ctx context.Context, ex sqlconnect.QueryExecutor, oldRef, newRef sqlconnect.RelationRef, o sqlconnect.MaterializationOptions) (string, error)

MoveTableWithOptions copies oldRef into a new table newRef in the same database, verifies equal row counts, then drops oldRef. A failed copy or count check drops nothing. A failed drop returns an error that joins sqlconnect.ErrDropOldTablePostCopy.

func (*DB) Ping 

func (db *DB) Ping() error

Ping checks reachability without validating materialization permissions.

func (*DB) PingContext 

func (db *DB) PingContext(ctx context.Context) error

PingContext checks reachability through the driver's transport and hello settings.

func (*DB) Prepare 

func (db *DB) Prepare(string) (*sql.Stmt, error)

Prepare is not supported: the driver sends every statement once.

func (*DB) PrepareContext 

func (db *DB) PrepareContext(context.Context, string) (*sql.Stmt, error)

PrepareContext is not supported: the driver sends every statement once.

func (*DB) RenameTable 

func (db *DB) RenameTable(ctx context.Context, oldRef, newRef sqlconnect.RelationRef) error

RenameTable renames a table inside one database. Another database returns CH_CROSS_DATABASE_MOVE_UNSUPPORTED.

func (*DB) SchemaExists 

func (db *DB) SchemaExists(ctx context.Context, schema sqlconnect.SchemaRef, opts ...sqlconnect.Option) (bool, error)

SchemaExists reports whether the database exists. A non-empty catalog filter returns false and runs no SQL.

func (*DB) StopQuery added in v1.35.0 

func (db *DB) StopQuery(ctx context.Context, queryID string) (sqlconnect.StopOutcome, error)

StopQuery implements sqlconnect.QueryController. It checks first, so it sends the stop statement only for a query that runs, then confirms. The check, the stop and each confirm are separate requests, and on a multi-replica service each can reach another replica. Every step is bounded, and every failure is a classified error: a refused setting (a readonly profile or a constraint) is CH_PERMISSION, and a query that still runs after the stop is CH_OUTCOME_UNKNOWN.

func (*DB) TableExists 

func (db *DB) TableExists(ctx context.Context, relation sqlconnect.RelationRef) (bool, error)

TableExists reports whether the table or view exists and is visible.

func (*DB) TruncateTable 

func (db *DB) TruncateTable(ctx context.Context, ref sqlconnect.RelationRef) error

TruncateTable removes every row. Only the shared test suite calls it.

func (*DB) ValidateContext 

func (db *DB) ValidateContext(ctx context.Context) (sqlconnect.ValidationResult, error)

ValidateContext runs the validation stages in order on one connection. Stages 1 to 4 are fatal; stage 5 only adds warnings. Each call owns its result.

Source Files

View all Source files

Directories

Path Synopsis
Package chtest starts digest-pinned ClickHouse containers through the rudder-go-kit ClickHouse resource and puts a fault-injecting proxy in front of them.
 Package chtest starts digest-pinned ClickHouse containers through the rudder-go-kit ClickHouse resource and puts a fault-injecting proxy in front of them.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.