Download the PHP package slkxmail/clickhouse-client without Composer

Clickhouse Client

A simple version of clickhouse client (using HTTP interface). This version provides the closest access to HTTP interface, allowing you to use maximum of the Clickhouse Database capabilities in your PHP applications.

Installation

Basic installation with composer

Configurations

You can pass additional settings in 2nd parameter, along with database name.

The full list of settings can be found in Settings section of the Clickhouse documentation.

You do not need do define all of this in case you are using default configurations.

For example if you need to create a client object with readonly access, pass "readonly" parameter.

Communication with Clickhouse Database happens using php-curl library. If you wish to control query execution more closely, you can pass a 4th parameter to Config constructor, containing php-curl library parameters.

For example if we would like to set a 5 second connection timeout, we would create a following config:

Full list of supported constants can be found in curl_setopt function documentation.

You can define credentials or settings after creating the config object

Functionality for changing basic connection information and curl settings is not implemented, because changing those settings should both conceptually and technically be considered a new client.

Client

Creating a client is fairly simple.

Reading from Clickhouse

There are several methods for reading data from Clickhouse.

Simple Query

This method is primarily used for getting statistics, aggregated data from Clickhouse.

Each client query returns a response with all the information about the connection performed and response.

Query data into Stream

It is possible to read data from Clickhouse directly into a stream - a file for example.

Query data into Closure (function-callable)

This method is useful when you intend to divide one Clickhouse response into several destinations.

Writing into Clickhouse

There are several ways to writing to the database as well.

Simple Insert

Most common way of writing to a database.

NOTE: clickhouse does not have escape mechanisms like MySQL / Oracle / etc. For save inserts please see other insert methods.

Rows Insert

The safest and easiest way to insert data into clickhouse table is to use "writeRows" method. The method takes first half of the insert statement as the first parameter and php array of rows as second. When inserting data method "writeRows" encodes the data into appropriate format for Clickhouse database to interpret. By default it is JSON format. Such approach does not require explicit escaping.

File Insert

Another way of inserting data is directly from a file.

NOTE: the format of the data in the file should match the one clickhouse is expecting

This method actually accepts data not only from a file, but from any php stream resource. Thus we can import data from other places, like memory (or anything that can be represented as a stream, really).

System Queries

Client object supports system queries. Such queries can manage database schema, processes and more.

In case of failure to perform the operation client throws an Exception.

It is also possible to change the database for the whole client.

This uses the same config object which is passed on "Client" object creation, so this code will also work.

Formats

There are several formats that Clickhouse support. This is used for retrieving and inserting data. Default format is set to JSON. When you perform simple select / insert queries data is encoded into JSON and transferred between client and Clickhouse. This does not work for Stream / Closure queries/writes. When performing any query/write you can change format of communication by passing a class name as the last parameter.

Ping

Clickhouse Database supports a ping method.

You can check if the database responds properly using "ping" method of the client.

In case of connection problems an Exception will be thrown.

Exception handling

Any request the client class makes can throw an exception.

It is a good practice to check for exceptions when performing query.

Support

In case of ANY issues with the library please create an Issue on GitHub or contact by email [email protected]