Skip to main content
Version: 0.3.x

Connecting to the Client

Document Type: Tutorial

Document Structure: Tutorial Purpose, Preparation, Step-by-Step Explanation & Examples, Related Document Recommendations;

Content Summary:

  1. What client or driver methods does ByConity provide for interacting with other systems?
  2. How to download and start these clients after deploying the cluster?

Command Line Interface (CLI)​

Docker Client​

If you have already installed Docker, you can establish a ByConity connection with the following command:

docker run -it yandex/clickhouse-client --host 127.0.0.1 --port 9000 --user default --password xxxx

The following options are all optional and depend on your situation:

  • --host xxx: Host IP or domain name
  • --port 9000: TCP port, default is 9000
  • --user default: Username
  • --password xxxx: Password

Clickhouse Client​

Byconity is compatible with clients provided by the ClickHouse open-source community.

curl -O 'https://builds.clickhouse.com/master/macos/clickhouse' \
&& chmod a+x ./clickhouse

sudo mv ./clickhouse /usr/local/bin/
  • Establish a connection:
clickhouse client --host 127.0.0.1 --password xxxx
  • You can view optional parameters with clickhouse client --help. The parameters here are consistent with those following docker run -it yandex/clickhouse-client ...

Drivers for Various Languages​

The open-source drivers for various languages provided by Clickhouse can be directly used for Byconity connections.

Python​

clickhouse-connect​

  • clickhouse-connect only supports python3
  • Installation: pip3 install clickhouse-connect
  • Example code:
import clickhouse_connect

# connect
client = clickhouse_connect.get_client(host='localhost', username='default', password='xxxx')

# query
query_result = client.query('SHOW DATABASES;')
print(query_result.result_set)

clickhouse-driver​

  • Python3 installation: pip3 install clickhouse-driver
  • Python2 installation: pip install clickhouse-driver
  • Example code:
from clickhouse_driver import Client
from clickhouse_driver import connect

# connect
client = Client(host='localhost', port=9000, user='default', password='xxxx')

# query
query_result = client.execute('SHOW DATABASES;')
print(query_result)

Go​

Connect using clickhouse-go​

  • Compared to ch-go below, clickhouse-go provides more friendly support for Go types and is recommended. It is implemented using ch-go underneath.
  • Install in your project with go get github.com/ClickHouse/clickhouse-go/v2
  • Example code:
package main

import (
 "context"
 "log"
 "net"
 "time"

 "github.com/ClickHouse/clickhouse-go/v2"
)

func main() {
 ctx := context.Background()

 // Configure connection parameters
 conn, err := clickhouse.Open(&clickhouse.Options{
 Addr:     []string{"127.0.0.1"},
 Auth:     clickhouse.Auth{Database: "my_db", Username: "default", Password: "xxxx"},
 DialContext: func(ctx context.Context, addr string) (net.Conn, error) {
 var d net.Dialer
 return d.DialContext(ctx, "tcp", addr)
 },
 Settings: clickhouse.Settings{
 "max_execution_time": 60,
 },
 DialTimeout:      time.Duration(10) * time.Second,
 MaxOpenConns:     5,
 MaxIdleConns:     5,
 ConnMaxLifetime:  time.Duration(10) * time.Minute,
 ConnOpenStrategy: clickhouse.ConnOpenInOrder,
 })
 if err != nil {
 log.Panic(err)
 }

 if err := conn.Ping(ctx); err != nil {
 log.Panic(err)
 }

 // Execute SQL
 if err := conn.Exec(ctx, "SHOW DATABASES;"); err != nil {
 log.Panic(err)
 }
}

Connect using ch-go​

  • ch-go provides better support for Clickhouse data types and slightly higher performance than clickhouse-go.
  • Install with go get github.com/ClickHouse/ch-go
  • Example code:
package main

import (
 "context"
 "fmt"

 "github.com/ClickHouse/ch-go"
 "github.com/ClickHouse/ch-go/proto"
)

func main() {
 ctx := context.Background()
 c, err := ch.Dial(ctx, ch.Options{Address: "localhost:9000"})
 if err != nil {
 panic(err)
 }
 var (
 numbers int
 data    proto.ColUInt64
 )
 if err := c.Do(ctx, ch.Query{
 Body: "SELECT number FROM system.numbers LIMIT 500000000",
 Result: proto.Results{
 {Name: "number", Data: &data},
 },
 // OnResult will be called on the next received data block.
 OnResult: func(ctx context.Context, b proto.Block) error {
 numbers += len(data)
 return nil
 },
 }); err != nil {
 panic(err)
 }
 fmt.Println("numbers:", numbers)
}

Java​

Connecting with clickhouse-jdbc

  • Install via Maven configuration:
<dependency>
    <!-- please stop using ru.yandex.clickhouse as it's been deprecated -->
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.3.2-patch11</version>
    <!-- use uber jar with all dependencies included, change classifier to http for smaller jar -->
    <classifier>all</classifier>
    <exclusions>
        <exclusion>
            <groupId>*</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>
  • Example code:
String url = "jdbc:ch://localhost:8123";
Properties properties = new Properties();
properties.setProperty("max_execution_time", "120");
ClickHouseDataSource dataSource = new ClickHouseDataSource(url, properties);
try (Connection conn = dataSource.getConnection("default", "password");
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("SHOW DATABASES;");
    while(rs.next()) {
        // ...
    }
}

HTTP​

ByConity also provides an HTTP connection method, allowing you to execute SQL using curl or Postman. Here's a curl example:

curl --location --request POST '127.0.0.1:8123/?max_execution_time=60&default_format=Native' \
--header 'Authorization: Basic xxx' \
--header 'Content-Type: text/plain' \
--data-raw 'SHOW DATABASES;'
  • The Basic Auth (username + password) encryption method is used, and the encrypted result corresponds to the --header 'Authorization: Basic xxx' above.
  • The SQL to be executed is directly written in the Body, corresponding to the --data-raw 'SHOW DATABASES;' above.
  • The default port for the HTTP interface is 8123.
  • Example parameters:
    • max_execution_time=60 specifies the maximum wait time (in seconds) for the query.
    • By default, the returned data is in TabSeparated format, but default_format can specify a different default format.

Reference Documentation​