clickhouse

README

GORM ClickHouse Driver

Clickhouse support for GORM

Quick Start

You can simply test your connection to your database with the following:

package main

import (
	"gorm.io/driver/clickhouse"
	"gorm.io/gorm"
)

type User struct {
	Name string
	Age  int
}

func main() {
	dsn := "clickhouse://gorm:gorm@localhost:9942/gorm?dial_timeout=10s&read_timeout=20s"
	db, err := gorm.Open(clickhouse.Open(dsn), &gorm.Config{})
	if err != nil {
		panic("failed to connect database")
	}

	// Auto Migrate
	db.AutoMigrate(&User{})
	// Set table options
	db.Set("gorm:table_options", "ENGINE=Distributed(cluster, default, hits)").AutoMigrate(&User{})

	// Set table cluster options
	db.Set("gorm:table_cluster_options", "on cluster default").AutoMigrate(&User{})

	// Insert
	db.Create(&User{Name: "Angeliz", Age: 18})

	// Select
	db.Find(&User{}, "name = ?", "Angeliz")

	// Batch Insert
	user1 := User{Age: 12, Name: "Bruce Lee"}
	user2 := User{Age: 13, Name: "Feynman"}
	user3 := User{Age: 14, Name: "Angeliz"}
	var users = []User{user1, user2, user3}
	db.Create(&users)
	// ...
}

Advanced Configuration

package main

import (
  std_ck "github.com/ClickHouse/clickhouse-go/v2"
  "gorm.io/driver/clickhouse"
  "gorm.io/gorm"
)

sqlDB, err := std_ck.OpenDB(&std_ck.Options{
	Addr: []string{"127.0.0.1:9999"},
	Auth: std_ck.Auth{
		Database: "default",
		Username: "default",
		Password: "",
	},
	TLS: &tls.Config{
		InsecureSkipVerify: true,
	},
	Settings: std_ck.Settings{
		"max_execution_time": 60,
	},
	DialTimeout: 5 * time.Second,
	Compression: &std_ck.Compression{
		std_ck.CompressionLZ4,
	},
	Debug: true,
})

func main() {
  db, err := gorm.Open(clickhouse.New(click.Config{
    Conn: sqlDB, // initialize with existing database conn
  })
}

package main

import (
  "gorm.io/driver/clickhouse"
  "gorm.io/gorm"
)

// refer to https://github.com/ClickHouse/clickhouse-go
var dsn = "clickhouse://username:password@host1:9000,host2:9000/database?dial_timeout=200ms&max_execution_time=60"

func main() {
  db, err := gorm.Open(clickhouse.New(click.Config{
    DSN: dsn,
    Conn: conn,                       // initialize with existing database conn
    DisableDatetimePrecision: true,   // disable datetime64 precision, not supported before clickhouse 20.4
    DontSupportRenameColumn: true,    // rename column not supported before clickhouse 20.4
    DontSupportEmptyDefaultValue: false,  // do not consider empty strings as valid default values
    SkipInitializeWithVersion: false, // smart configure based on used version
    DefaultGranularity: 3,            // 1 granule = 8192 rows
    DefaultCompression: "LZ4",        // default compression algorithm. LZ4 is lossless
    DefaultIndexType: "minmax",       // index stores extremes of the expression
    DefaultTableEngineOpts: "ENGINE=MergeTree() ORDER BY tuple()",
  }), &gorm.Config{})
}

Checkout https://gorm.io for details.

Documentation

Index

• Variables
• func New(config Config) gorm.Dialector
• func Open(dsn string) gorm.Dialector
• type Config
• type Dialector
  • func (dialector Dialector) BindVarTo(writer clause.Writer, stmt *gorm.Statement, v interface{})
  • func (dialector Dialector) ClauseBuilders() map[string]clause.ClauseBuilder
  • func (dialector *Dialector) Create(db *gorm.DB)
  • func (dialector Dialector) DataTypeOf(field *schema.Field) string
  • func (dialector Dialector) DefaultValueOf(field *schema.Field) clause.Expression
  • func (dialector Dialector) Explain(sql string, vars ...interface{}) string
  • func (dialector *Dialector) Initialize(db *gorm.DB) (err error)
  • func (dialector Dialector) Migrator(db *gorm.DB) gorm.Migrator
  • func (dialector Dialector) Name() string
  • func (dialector Dialector) QuoteTo(writer clause.Writer, str string)
  • func (dialectopr Dialector) RollbackTo(tx *gorm.DB, name string) error
  • func (dialectopr Dialector) SavePoint(tx *gorm.DB, name string) error
  • func (dialector *Dialector) Update(db *gorm.DB)
• type Migrator
  • func (m Migrator) AddColumn(value interface{}, field string) error
  • func (m Migrator) AlterColumn(value interface{}, field string) error
  • func (m Migrator) BuildIndexOptions(opts []schema.IndexOption, stmt *gorm.Statement) (results []interface{})
  • func (m Migrator) ColumnTypes(value interface{}) ([]gorm.ColumnType, error)
  • func (m Migrator) CreateIndex(value interface{}, name string) error
  • func (m Migrator) CreateTable(models ...interface{}) error
  • func (m Migrator) CurrentDatabase() (name string)
  • func (m Migrator) DropColumn(value interface{}, name string) error
  • func (m Migrator) DropIndex(value interface{}, name string) error
  • func (m Migrator) FullDataTypeOf(field *schema.Field) (expr clause.Expr)
  • func (m Migrator) GetTables() (tableList []string, err error)
  • func (m Migrator) HasColumn(value interface{}, field string) bool
  • func (m Migrator) HasIndex(value interface{}, name string) bool
  • func (m Migrator) HasTable(value interface{}) bool
  • func (m Migrator) RenameColumn(value interface{}, oldName, newName string) error
  • func (m Migrator) RenameIndex(value interface{}, oldName, newName string) error
• type UpdateLocalTable
  • func (t UpdateLocalTable) Build(clause.Builder)
  • func (t UpdateLocalTable) ModifySQL(sql string) string
  • func (t UpdateLocalTable) ModifyStatement(stmt *gorm.Statement)

Variables

var (
	ErrRenameColumnUnsupported = errors.New("renaming column is not supported in your clickhouse version < 20.4")
	ErrRenameIndexUnsupported  = errors.New("renaming index is not supported")
	ErrCreateIndexFailed       = errors.New("failed to create index with name")
)

Errors enumeration

Functions

func New

func New(config Config) gorm.Dialector

func Open

func Open(dsn string) gorm.Dialector

Types

type Config

type Config struct {
	DriverName                   string
	DSN                          string
	Conn                         gorm.ConnPool
	DisableDatetimePrecision     bool
	DontSupportRenameColumn      bool
	DontSupportColumnPrecision   bool
	DontSupportEmptyDefaultValue bool
	SkipInitializeWithVersion    bool
	DefaultGranularity           int    // 1 granule = 8192 rows
	DefaultCompression           string // default compression algorithm. LZ4 is lossless
	DefaultIndexType             string // index stores extremes of the expression
	DefaultTableEngineOpts       string
	PoolMaxIdleCount             int           // zero means defaultMaxIdleConns; negative means 0
	PoolMaxOpenCount             int           // <= 0 means unlimited
	PoolMaxLifetime              time.Duration // maximum amount of time a connection may be reused
	PoolMaxIdleTime              time.Duration // maximum amount of time a connection may be idle before being closed
}

type Dialector

type Dialector struct {
	*Config

	Version string
	// contains filtered or unexported fields
}

func (Dialector) BindVarTo

func (dialector Dialector) BindVarTo(writer clause.Writer, stmt *gorm.Statement, v interface{})

func (Dialector) ClauseBuilders

func (dialector Dialector) ClauseBuilders() map[string]clause.ClauseBuilder

func (*Dialector) Create

func (dialector *Dialector) Create(db *gorm.DB)

func (Dialector) DataTypeOf

func (dialector Dialector) DataTypeOf(field *schema.Field) string

func (Dialector) DefaultValueOf

func (dialector Dialector) DefaultValueOf(field *schema.Field) clause.Expression

func (Dialector) Explain

func (dialector Dialector) Explain(sql string, vars ...interface{}) string

func (*Dialector) Initialize

func (dialector *Dialector) Initialize(db *gorm.DB) (err error)

func (Dialector) Migrator

func (dialector Dialector) Migrator(db *gorm.DB) gorm.Migrator

func (Dialector) Name

func (dialector Dialector) Name() string

func (Dialector) QuoteTo

func (dialector Dialector) QuoteTo(writer clause.Writer, str string)

func (Dialector) RollbackTo

func (dialectopr Dialector) RollbackTo(tx *gorm.DB, name string) error

func (Dialector) SavePoint

func (dialectopr Dialector) SavePoint(tx *gorm.DB, name string) error

func (*Dialector) Update

func (dialector *Dialector) Update(db *gorm.DB)

type Migrator

type Migrator struct {
	migrator.Migrator
	Dialector
}

func (Migrator) AddColumn

func (m Migrator) AddColumn(value interface{}, field string) error

func (Migrator) AlterColumn

func (m Migrator) AlterColumn(value interface{}, field string) error

func (Migrator) BuildIndexOptions

func (m Migrator) BuildIndexOptions(opts []schema.IndexOption, stmt *gorm.Statement) (results []interface{})

func (Migrator) ColumnTypes

func (m Migrator) ColumnTypes(value interface{}) ([]gorm.ColumnType, error)

ColumnTypes return columnTypes []gorm.ColumnType and execErr error

func (Migrator) CreateIndex

func (m Migrator) CreateIndex(value interface{}, name string) error

func (Migrator) CreateTable

func (m Migrator) CreateTable(models ...interface{}) error

func (Migrator) CurrentDatabase

func (m Migrator) CurrentDatabase() (name string)

func (Migrator) DropColumn

func (m Migrator) DropColumn(value interface{}, name string) error

func (Migrator) DropIndex

func (m Migrator) DropIndex(value interface{}, name string) error

func (Migrator) FullDataTypeOf

func (m Migrator) FullDataTypeOf(field *schema.Field) (expr clause.Expr)

func (Migrator) GetTables

func (m Migrator) GetTables() (tableList []string, err error)

func (Migrator) HasColumn

func (m Migrator) HasColumn(value interface{}, field string) bool

func (Migrator) HasIndex

func (m Migrator) HasIndex(value interface{}, name string) bool

func (Migrator) HasTable

func (m Migrator) HasTable(value interface{}) bool

func (Migrator) RenameColumn

func (m Migrator) RenameColumn(value interface{}, oldName, newName string) error

NOTE: Only supported after ClickHouse 20.4 and above. See: https://github.com/ClickHouse/ClickHouse/issues/146

func (Migrator) RenameIndex

func (m Migrator) RenameIndex(value interface{}, oldName, newName string) error

type UpdateLocalTable

type UpdateLocalTable struct {
	Table  string
	Prefix string
	Suffix string
}

func (UpdateLocalTable) Build

func (t UpdateLocalTable) Build(clause.Builder)

Build implements clause.Expression interface

func (UpdateLocalTable) ModifySQL

func (t UpdateLocalTable) ModifySQL(sql string) string

func (UpdateLocalTable) ModifyStatement

func (t UpdateLocalTable) ModifyStatement(stmt *gorm.Statement)

ModifyStatement modify operation mode