Configuration

A ClickHouse connection uses the clickhouse driver. The package merges its defaults into config('database.connections.clickhouse'). The values of config/clickhouse.php override the defaults. A connection in config/database.php overrides both. See Installation.

Options

Option	.env variable	Default	Description
host	CLICKHOUSE_HOST	127.0.0.1	Host of the server
port	CLICKHOUSE_PORT	8123	HTTP port of the server
database	CLICKHOUSE_DATABASE	default	Database of the connection
username	CLICKHOUSE_USERNAME	default	User name
password	CLICKHOUSE_PASSWORD	''	Password
https	CLICKHOUSE_HTTPS	false	Use HTTPS
timeout_connect	CLICKHOUSE_TIMEOUT_CONNECT	2	Seconds to wait for a connection. See Timeouts.
timeout_query	CLICKHOUSE_TIMEOUT_QUERY	2	Seconds that a request can take. See Timeouts.
retries	CLICKHOUSE_RETRIES	0	Number of retries of a failed request. See Retries.
retry_on	CLICKHOUSE_RETRY_ON	reads	reads, any or unsent: the failed requests that the retries send again. See Retries.
settings		[]	ClickHouse settings for each query of the connection
use_lightweight_delete	CLICKHOUSE_USE_LIGHTWEIGHT_DELETE	false	delete() without an argument sends a lightweight DELETE FROM. See Deletions.
engine	CLICKHOUSE_ENGINE	null	Engine of a table that Schema::create() creates without engine(). null is MergeTree().
default_index_type	CLICKHOUSE_DEFAULT_INDEX_TYPE	null	Type of a data-skipping index that has no type, such as minmax
datetime_precision	CLICKHOUSE_DATETIME_PRECISION	second	second or microsecond, or a DateTimePrecision case. See Dates and times.
insert_format	CLICKHOUSE_INSERT_FORMAT	Values	Values or JSONEachRow, or a Format case. See JSONEachRow inserts.
use_on_cluster	CLICKHOUSE_USE_ON_CLUSTER	false	Send delete(), update(), truncate() and optimize() ON CLUSTER. It needs cluster_name.
cluster			List of nodes. It replaces host and port. See Clusters.
cluster_name			Cluster name of the server config, for ON CLUSTER. See Clusters.

The connection passes its config to the smi2 client, so the client's own options work too: sslCA, the CA file of an HTTPS server, auth_method, curl_options and readonly.

The options datetime_precision, insert_format and use_on_cluster are off by default. Without them, the package writes dates with seconds, inserts in Values and sends mutations to the active node.

DB::connection('clickhouse')->table() and query() return the package's QueryBuilder, Laravel's query builder with the ClickHouse clauses. No option changes it. See Query builder basics.

Validation

The connection checks its options when Laravel creates it, before it pings a node. An incorrect value throws an InvalidArgumentException:

The [datetime_precision] option of the ClickHouse connection [clickhouse] must be 'second' or 'microsecond', [millisecond] given.

use_on_cluster without cluster_name also throws.

datetime_precision and insert_format take a string in any letter case, with or without surrounding spaces, or a case of the Oralunal\LaravelClickHouse\Enums\DateTimePrecision and Oralunal\LaravelClickHouse\Enums\Format enums:

use Oralunal\LaravelClickHouse\Enums\DateTimePrecision;
use Oralunal\LaravelClickHouse\Enums\Format;

'datetime_precision' => DateTimePrecision::Microsecond,
'insert_format' => Format::JsonEachRow,

Settings

The settings option sends ClickHouse settings with each query of the connection:

'settings' => [
    'max_partitions_per_insert_block' => 300,
],

To set a setting for one query, use settings() of the query builder.

Read the options

Method	Returns
getDateTimePrecision()	DateTimePrecision::Second or DateTimePrecision::Microsecond
getInsertFormat()	Format::Values or Format::JsonEachRow
formatDateTime($date)	A date as the connection writes it, without quotes: 2024-01-02 03:04:05, or 2024-01-02 03:04:05.500000 at microsecond
getClusterName()	The cluster_name option without surrounding spaces, or null when it is blank
hasClusterNodes()	true when the cluster option lists nodes
getDefaultCluster()	The cluster of ON CLUSTER when use_on_cluster is on, or null. See Clusters.
getServerVersion()	The version of the server of the active node, for example 24.8.14.39
getDriverTitle()	ClickHouse, the name that php artisan db:show shows
newLiteralGrammar()	A LiteralGrammar that writes values as ClickHouse literals, as the connection writes them, with dates at datetime_precision. See Literals.

Call them on the connection: DB::connection('clickhouse')->getServerVersion(). Connection::createWithClient($config) makes a connection and its nodes from a config array. The clickhouse driver uses it. It checks the options before it pings a node.