GORM ClickHouse Driver

To connect to ClickHouse using GORM, use clickhouse.Open(dsn) with a valid DSN string. You can perform standard GORM operations like AutoMigrate, Create, and Find.

This driver also supports setting ClickHouse-specific table options and cluster options during migration using db.Set with the following keys:

• gorm:table_options: Used to specify the ClickHouse engine (e.g., ENGINE=Distributed(...)).
• gorm:table_cluster_options: Used to specify cluster-specific settings (e.g., on cluster default).

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 (e.g. Distributed engine)
	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
	users := []User{
		{Age: 12, Name: "Bruce Lee"},
		{Age: 13, Name: "Feynman"},
		{Age: 14, Name: "Angeliz"},
	}
	db.Create(&users)
}

If you need fine-grained control over the underlying ClickHouse connection (e.g., setting TLS, compression, or specific driver settings), you can initialize a standard clickhouse-go connection and pass it to clickhouse.New using the Conn field in the configuration.

package main

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

func main() {
  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,
  })
  if err != nil {
    panic(err)
  }

  db, err := gorm.Open(clickhouse.New(clickhouse.Config{
    Conn: sqlDB, // initialize with existing database conn
  }), &gorm.Config{})
  if err != nil {
    panic(err)
  }
}

When using clickhouse.New(config), you can provide several configuration options to tune the driver behavior and compatibility with specific ClickHouse versions.

Note: Refer to the official clickhouse-go documentation for DSN format and connection string details.

package main

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

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(clickhouse.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{})
  if err != nil {
    panic(err)
  }
}

The Config struct allows you to fine-tune how GORM interacts with ClickHouse. Key configuration options include:

• DSN: The connection string.
• Conn: An existing gorm.ConnPool to use instead of opening a new connection.
• DisableDatetimePrecision: If true, prevents adding precision to DateTime64 types.
• DontSupportRenameColumn: Automatically set to true if the ClickHouse version is < 20.4.
• DontSupportColumnPrecision: Automatically set to true if the ClickHouse version is < 21.11.
• DefaultGranularity: Default is 3 (1 granule = 8192 rows).
• DefaultCompression: Default is LZ4.
• DefaultIndexType: Default is minmax.
• DefaultTableEngineOpts: Default is ENGINE=MergeTree() ORDER BY tuple().
• InformationSchemaTablesTableTypeString: Automatically set to true if ClickHouse version is >= 23.9.

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

InformationSchemaTablesTableTypeString bool // information_schema.tables.table_type is String
}

In ClickHouse, updates often need to be performed on the local part of a distributed table rather than the distributed table itself. You can use the UpdateLocalTable struct to intercept GORM update statements and modify the target table name using a prefix, a suffix, or a complete replacement.

To use this, call ModifyStatement on your GORM statement. This is typically done within a custom callback or by accessing the statement directly if you are extending the driver's behavior.

Supported modification modes:

• Suffix: Appends a string to the end of the table name.
• Prefix: Prepends a string to the beginning of the table name.
• Table: Replaces the table name entirely.

// Example of how UpdateLocalTable might be used to target a local table
// Note: This requires access to the gorm.Statement object
db.Statement.Settings.Store("gorm:clickhouse:update_local_table_name", clickhouse.UpdateLocalTable{
    Suffix: "_local",
})