phpClickHouse

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

Downloads Packagist Licence

Features

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

Guide Description
Quick Start & Basics Connection, select, insert, write, Statement API
Async Queries Parallel selects, batch file inserts, error handling
Bindings & Conditions Parameter binding, SQL templates, conditions
Settings & Configuration Timeouts, compression, HTTPS, auth methods, sessions

Advanced

Guide Description
Native Query Parameters Server-side {name:Type} binding
ClickHouse Types Int64, Decimal, UUID, IPv4/IPv6, DateTime64, Date32, Map, Tuple
Generators Memory-efficient selectGenerator() for large resultsets
Per-Query Settings Override settings per request
Streaming streamRead, streamWrite, closures, gzip
Cluster Multi-node setup, replicas, truncate, master node

Reference

Guide Description
Structured Exceptions Error codes, exception names, query ID
Progress Function Real-time progress for SELECT and INSERT
INSERT Statistics written_rows, written_bytes via X-ClickHouse-Summary
Advanced Features Partitions, table sizes, write-to-file, logging, debug

Version Compatibility

PHP phpClickHouse
5.6 <= 1.1.2
7.2 <= 1.3.10
7.3 1.4.x – 1.5.x
8.0+ >= 1.6.0