clickhouse

README

ClickHouse Handler Library

This library provides a utility for interacting with a ClickHouse database. It includes functionality for loading configuration, establishing a connection, executing queries, and managing the database session.

Features

• Load ClickHouse configuration from environment variables.
• Establish a secure connection to the ClickHouse database.
• Execute queries and statements.
• Manage the database session lifecycle.

Configuration

The library expects the following environment variables to be set:

• CLICKHOUSE_HOSTNAME: The hostname of the ClickHouse server.
• CLICKHOUSE_USERNAME: The username for authentication.
• CLICKHOUSE_PASSWORD: The password for authentication.
• CLICKHOUSE_DATABASE: The name of the database to connect to.
• CLICKHOUSE_PORT: The port number of the ClickHouse server.
• CLICKHOUSE_SKIP_VERIFY: Whether to skip TLS verification (true or false).

Usage

Loading Configuration

Use the ClickhouseLoadConfig function to load the configuration from environment variables:

config, err := ClickhouseLoadConfig()
if err != nil {
    log.Fatalf("Failed to load ClickHouse configuration: %v", err.Error())
}

Creating a ClickHouse Session

Use the NewClickhouseSession function to create a new session:

ctx := context.Background()
session, err := NewClickhouseSession(config, ctx)
if err != nil {
    log.Fatalf("Failed to create ClickHouse session: %v", err.Error())
}
defer session.Close()

Executing Queries

Querying Data

Use the Query method to execute a query and retrieve rows:

rows, err := session.Query(ctx, "SELECT * FROM my_table")
if err != nil {
    log.Fatalf("Query failed: %v", err.Error())
}
defer rows.Close()

Executing Statements

Use the Exec method to execute a statement:

err := session.Exec(ctx, "INSERT INTO my_table (id, name) VALUES (1, 'example')")
if err != nil {
    log.Fatalf("Execution failed: %v", err.Error())
}

Closing the Session

Always close the session when done:

err := session.Close()
if err != nil {
    log.Fatalf("Failed to close ClickHouse session: %v", err.Error())
}

Error Handling

Ensure proper error handling when loading configuration, creating a session, or executing queries, as invalid credentials or connection issues will result in errors.

Dependencies

This library uses the following dependencies:

• ClickHouse Go: Go client for ClickHouse.
• spf13/viper: Configuration management for Go.

Documentation

Index

• Variables
• func ClickhouseValidateConfig(clickhouseConfig *ClickhouseConfig) error
• func Named(name string, value interface{}) driver.NamedValue
• type ClickhouseConfig
  • func ClickhouseLoadConfig() (*ClickhouseConfig, error)
• type ClickhouseSession
  • func NewClickhouseSession(ch *ClickhouseConfig, ctx context.Context) (*ClickhouseSession, error)
  • func (ch *ClickhouseSession) Close() error
  • func (ch *ClickhouseSession) Conn() Conn
  • func (chsession *ClickhouseSession) Connect(ch *ClickhouseConfig, ctx context.Context) error
  • func (ch *ClickhouseSession) Exec(ctx context.Context, stmt string) error
  • func (ch *ClickhouseSession) ExecWithArgs(ctx context.Context, stmt string, args ...interface{}) error
  • func (ch *ClickhouseSession) Ping(ctx context.Context) error
  • func (ch *ClickhouseSession) Query(ctx context.Context, query string) (Rows, error)
  • func (ch *ClickhouseSession) QueryRow(ctx context.Context, query string, args ...interface{}) Row
  • func (ch *ClickhouseSession) QueryWithArgs(ctx context.Context, query string, args ...interface{}) (Rows, error)
• type ClickhouseSessionInterface
  • func NewSessionFromConn(conn Conn) ClickhouseSessionInterface
• type ConfigLoaderInterface
• type ConfigValidatorInterface
• type Conn
• type DefaultConfigLoader
  • func (c *DefaultConfigLoader) LoadConfig() (*ClickhouseConfig, error)
• type DefaultConfigValidator
  • func (v *DefaultConfigValidator) ValidateConfig(config *ClickhouseConfig) error
• type DefaultSessionFactory
  • func (f *DefaultSessionFactory) NewSession(ch *ClickhouseConfig, ctx context.Context) (ClickhouseSessionInterface, error)
• type Options
• type Row
• type Rows
• type SessionFactoryInterface

Variables

var DefaultRetryIntervals = []time.Duration{2 * time.Second, 3 * time.Second, 5 * time.Second}

DefaultRetryIntervals are the default retry intervals for production use. This can be overridden in tests for faster execution.

Functions

func ClickhouseValidateConfig

func ClickhouseValidateConfig(clickhouseConfig *ClickhouseConfig) error

validateConfig validates the loaded configuration.

func Named

func Named(name string, value interface{}) driver.NamedValue

Named creates a named parameter for use in queries. Re-exported from clickhouse-go for convenience.

Types

type ClickhouseConfig

type ClickhouseConfig struct {
	ChHostname   string `mapstructure:"chhostname"`
	ChUsername   string `mapstructure:"chusername"`
	ChPassword   string `mapstructure:"chpassword"`
	ChDatabase   string `mapstructure:"chdatabase"`
	ChSkipVerify string `mapstructure:"chskipverify"`
	ChPort       string `mapstructure:"chport"`
}

func ClickhouseLoadConfig

func ClickhouseLoadConfig() (*ClickhouseConfig, error)

LoadConfig loads the configuration from environment variables using Viper. Uses an isolated viper instance to avoid global state pollution that could affect other packages using viper with different env prefixes.

type ClickhouseSession

type ClickhouseSession struct {
	// contains filtered or unexported fields
}

ClickhouseSession implements ClickhouseSessionInterface

func NewClickhouseSession

func NewClickhouseSession(ch *ClickhouseConfig, ctx context.Context) (*ClickhouseSession, error)

NewClickhouseSession creates a new Clickhouse session.

func (*ClickhouseSession) Close

func (ch *ClickhouseSession) Close() error

Close ClickHouse connection

func (*ClickhouseSession) Conn

func (ch *ClickhouseSession) Conn() Conn

return ClickHouse connection

func (*ClickhouseSession) Connect

func (chsession *ClickhouseSession) Connect(ch *ClickhouseConfig, ctx context.Context) error

Connect to ClickHouse database

func (*ClickhouseSession) Exec

func (ch *ClickhouseSession) Exec(ctx context.Context, stmt string) error

Exec ClickHouse query

func (*ClickhouseSession) ExecWithArgs

func (ch *ClickhouseSession) ExecWithArgs(ctx context.Context, stmt string, args ...interface{}) error

ExecWithArgs executes a statement with arguments

func (*ClickhouseSession) Ping

func (ch *ClickhouseSession) Ping(ctx context.Context) error

Ping verifies the connection to ClickHouse is alive.

func (*ClickhouseSession) Query

func (ch *ClickhouseSession) Query(ctx context.Context, query string) (Rows, error)

Query ClickHouse database

func (*ClickhouseSession) QueryRow

func (ch *ClickhouseSession) QueryRow(ctx context.Context, query string, args ...interface{}) Row

QueryRow executes a query with arguments and returns a single row Note: QueryRow doesn't return an error directly; errors are deferred until Scan() is called. Therefore, retry logic is not applicable here.

func (*ClickhouseSession) QueryWithArgs

func (ch *ClickhouseSession) QueryWithArgs(ctx context.Context, query string, args ...interface{}) (Rows, error)

QueryWithArgs executes a query with arguments and returns rows

type ClickhouseSessionInterface

type ClickhouseSessionInterface interface {
	Connect(ch *ClickhouseConfig, ctx context.Context) error
	Ping(ctx context.Context) error
	Query(ctx context.Context, query string) (Rows, error)
	QueryWithArgs(ctx context.Context, query string, args ...interface{}) (Rows, error)
	QueryRow(ctx context.Context, query string, args ...interface{}) Row
	Exec(ctx context.Context, stmt string) error
	ExecWithArgs(ctx context.Context, stmt string, args ...interface{}) error
	Close() error
	Conn() Conn
}

ClickhouseSessionInterface defines the interface for ClickHouse session operations

func NewSessionFromConn

func NewSessionFromConn(conn Conn) ClickhouseSessionInterface

NewSessionFromConn creates a ClickhouseSessionInterface from an existing connection. This is useful for backward compatibility or when you already have an established connection.

type ConfigLoaderInterface

type ConfigLoaderInterface interface {
	LoadConfig() (*ClickhouseConfig, error)
}

ConfigLoaderInterface defines the interface for configuration loading

type ConfigValidatorInterface

type ConfigValidatorInterface interface {
	ValidateConfig(config *ClickhouseConfig) error
}

ConfigValidatorInterface defines the interface for configuration validation

type Conn

type Conn = driver.Conn

Conn is the ClickHouse connection type

type DefaultConfigLoader

type DefaultConfigLoader struct{}

DefaultConfigLoader implements ConfigLoaderInterface

func (*DefaultConfigLoader) LoadConfig

func (c *DefaultConfigLoader) LoadConfig() (*ClickhouseConfig, error)

LoadConfig implements ConfigLoaderInterface

type DefaultConfigValidator

type DefaultConfigValidator struct{}

DefaultConfigValidator implements ConfigValidatorInterface

func (*DefaultConfigValidator) ValidateConfig

func (v *DefaultConfigValidator) ValidateConfig(config *ClickhouseConfig) error

ValidateConfig implements ConfigValidatorInterface

type DefaultSessionFactory

type DefaultSessionFactory struct{}

DefaultSessionFactory implements SessionFactoryInterface

func (*DefaultSessionFactory) NewSession

func (f *DefaultSessionFactory) NewSession(
	ch *ClickhouseConfig,
	ctx context.Context,
) (ClickhouseSessionInterface, error)

NewSession implements SessionFactoryInterface

type Options

type Options = clickhouse.Options

Options is the ClickHouse connection options type

type Row

type Row = driver.Row

Row represents a single query result row

type Rows

type Rows = driver.Rows

Rows represents query result rows

type SessionFactoryInterface

type SessionFactoryInterface interface {
	NewSession(ch *ClickhouseConfig, ctx context.Context) (ClickhouseSessionInterface, error)
}

SessionFactoryInterface defines the interface for creating ClickHouse sessions