layout: default title: phpClickHouse

phpClickHouse

PHP client for ClickHouse — fast, lightweight, zero dependencies beyond ext-curl.

Features

• Sync & async (parallel) SELECT queries
• Native query parameters — server-side {name:Type} binding, SQL injection impossible
• Rich type system — Boolean, Int64, Decimal, UUID, IPv4/IPv6, DateTime64, Date32, Map, Tuple
• Bulk inserts: arrays, CSV files, streams
• Generators — memory-efficient iteration for large resultsets
• HTTP compression (gzip) for inserts
• Parameter bindings & SQL templates
• Per-query settings — override ClickHouse settings per request
• Cluster support — auto-discovery, health checks, replicas
• Streaming read/write with closures
• Progress callbacks for SELECT and INSERT
• Structured exceptions — ClickHouse error name, query ID
• Sessions, write-to-file, INSERT statistics
• HTTPS, SSL CA, IPv6 support
• Multiple auth methods (none, header, basic auth, query string)

Installation

composer require smi2/phpclickhouse

Requires PHP 8.0+, ext-curl, ext-json.

Quick Start

$db = new ClickHouseDB\Client([
    'host'     => '127.0.0.1',
    'port'     => '8123',
    'username' => 'default',
    'password' => '',
]);

$db->database('default');
$db->setTimeout(10);
$db->setConnectTimeOut(5);
$db->ping(true);

Select

$statement = $db->select('SELECT * FROM my_table WHERE id = :id', ['id' => 42]);

$statement->rows();      // all rows
$statement->fetchOne();  // first row
$statement->count();     // row count

Native Query Parameters

$result = $db->selectWithParams(
    'SELECT * FROM users WHERE id = {id:UInt32} AND name = {name:String}',
    ['id' => 42, 'name' => 'Alice']
);

Insert

$db->insert('my_table',
    [
        [time(), 'key1', 100],
        [time(), 'key2', 200],
    ],
    ['event_time', 'key', 'value']
);

Generator (large resultsets)

foreach ($db->selectGenerator('SELECT * FROM huge_table') as $row) {
    processRow($row);
}

Documentation

Core

Advanced

Reference

Version Compatibility

Links

• GitHub
• Packagist
• Changelog
• habr.com — part 1
• habr.com — part 2