Skip to content

ClickHouse

Since v0.23.0

Introduction

The Testcontainers module for ClickHouse.

Adding this module to your project dependencies

Please run the following command to add the ClickHouse module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/clickhouse

Usage example

ctx := context.Background()

user := "clickhouse"
password := "password"
dbname := "testdb"

clickHouseContainer, err := clickhouse.Run(ctx,
    "clickhouse/clickhouse-server:23.3.8.21-alpine",
    clickhouse.WithUsername(user),
    clickhouse.WithPassword(password),
    clickhouse.WithDatabase(dbname),
    clickhouse.WithInitScripts(filepath.Join("testdata", "init-db.sh")),
    clickhouse.WithConfigFile(filepath.Join("testdata", "config.xml")),
)
defer func() {
    if err := testcontainers.TerminateContainer(clickHouseContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

Module Reference

Run function

Info

The RunContainer(ctx, opts...) function is deprecated and will be removed in the next major release of Testcontainers for Go.

The ClickHouse module exposes one entrypoint function to create the ClickHouse container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ClickHouseContainer, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Container Ports

Here you can find the list with the default ports used by the ClickHouse container.

httpPort   = nat.Port("8123/tcp")
nativePort = nat.Port("9000/tcp")

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "clickhouse/clickhouse-server:23.3.8.21-alpine").

Container Options

When starting the ClickHouse container, you can pass options in a variadic way to configure it.

Set username, password and database name

If you need to set a different database, and its credentials, you can use WithUsername, WithPassword, WithDatabase options. E.g. WithUsername("user"), WithPassword("password"), WithDatabase("db").

Info

The default values for the username is default, for password is clickhouse and for the default database name is clickhouse.

WithInitScripts

If you would like to do additional initialization in the ClickHouse container, add one or more *.sql, *.sql.gz, or *.sh scripts to the container request. Those files will be copied after the container is created but before it's started under /docker-entrypoint-initdb.d. According to ClickHouse Docker image, it will run any *.sql files, run any executable *.sh scripts, and source any non-executable *.sh scripts found in that directory to do further initialization before starting the service.

ctr, err := clickhouse.Run(ctx,
    "clickhouse/clickhouse-server:23.3.8.21-alpine",
    clickhouse.WithUsername(user),
    clickhouse.WithPassword(password),
    clickhouse.WithDatabase(dbname),
    clickhouse.WithInitScripts(filepath.Join("testdata", "init-db.sh")),
)
testcontainers.CleanupContainer(t, ctr)
require.NoError(t, err)

#!/bin/bash
set -e

clickhouse-client \
  --user "$CLICKHOUSE_USER" \
  --password "$CLICKHOUSE_PASSWORD" \
  --database "$CLICKHOUSE_DB" \
  --query "create table if not exists test_table (id UInt64) engine = MergeTree PRIMARY KEY (id) ORDER BY (id) SETTINGS index_granularity = 8192; INSERT INTO test_table (id) VALUES (1);" --multiquery

Zookeeper

Clusterized ClickHouse requires to start Zookeeper and pass link to it via config.xml.

zkPort := nat.Port("2181/tcp")

zkcontainer, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
    ContainerRequest: testcontainers.ContainerRequest{
        ExposedPorts: []string{zkPort.Port()},
        Image:        "zookeeper:3.7",
        WaitingFor:   wait.ForListeningPort(zkPort),
    },
    Started: true,
})
testcontainers.CleanupContainer(t, zkcontainer)
require.NoError(t, err)

ipaddr, err := zkcontainer.ContainerIP(ctx)
require.NoError(t, err)

ctr, err := clickhouse.Run(ctx,
    "clickhouse/clickhouse-server:23.3.8.21-alpine",
    clickhouse.WithUsername(user),
    clickhouse.WithPassword(password),
    clickhouse.WithDatabase(dbname),
    clickhouse.WithZookeeper(ipaddr, zkPort.Port()),
)
testcontainers.CleanupContainer(t, ctr)
require.NoError(t, err)

Warning

The WithZookeeper option will panic if it's not possible to create the Zookeeper config file.

WithConfigFile

If you need to set a custom configuration, the module provides the WithConfigFile option to pass the path to a custom configuration file in XML format.

<clickhouse>
  <allow_no_password>1</allow_no_password>
</clickhouse>

In the case you want to pass a YAML configuration file, you can use the WithYamlConfigFile option.

allow_no_password: true

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Container Methods

The ClickHouse container exposes the following methods:

ConnectionHost

This method returns the host and port of the ClickHouse container, using the default, native 9000/tcp port. E.g. localhost:9000

connectionHost, err := ctr.ConnectionHost(ctx)

ConnectionString

This method returns the dsn connection string to connect to the ClickHouse container, using the default, native 9000/tcp port obtained from the ConnectionHost method. It's possible to pass extra parameters to the connection string, e.g. dial_timeout=300ms or skip_verify=false, in a variadic way.

e.g. clickhouse://default:pass@localhost:9000?dial_timeout=300ms&skip_verify=false

connectionString, err := ctr.ConnectionString(ctx, "debug=true")