PHPackages                             lucasacoutinho/ext-clickhouse - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. lucasacoutinho/ext-clickhouse

ActivePhp-ext[HTTP & Networking](/categories/http)

lucasacoutinho/ext-clickhouse
=============================

Native TCP ClickHouse client extension for PHP.

v1.0.3(1mo ago)00[3 PRs](https://github.com/lucasacoutinho/ext-clickhouse/pulls)MITShellPHP >=7.4 <8.6CI passing

Since May 27Pushed 1mo agoCompare

[ Source](https://github.com/lucasacoutinho/ext-clickhouse)[ Packagist](https://packagist.org/packages/lucasacoutinho/ext-clickhouse)[ RSS](/packages/lucasacoutinho-ext-clickhouse/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (4)DependenciesVersions (8)Used By (0)

ext-clickhouse
==============

[](#ext-clickhouse)

A PHP extension providing native TCP access to ClickHouse using the [clickhouse-cpp](https://github.com/ClickHouse/clickhouse-cpp) C++ client library. Communicates over the ClickHouse native protocol with LZ4/ZSTD compression support.

Requirements
------------

[](#requirements)

- PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, or 8.5
- C++17 compiler (GCC 8+ or Clang 7+)

PHP version support
-------------------

[](#php-version-support)

CI builds and tests the extension on PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, and 8.5.

On PHP 8.1+, `ClickHouse\Driver\CompressionMethod` and `ClickHouse\Driver\Type` are native backed enums. On PHP 7.4 and 8.0, the same names are final classes with integer constants, so code can still use constants such as `CompressionMethod::LZ4`. Methods returning `Type` return integer constants on PHP 7.4 and 8.0, and enum cases on PHP 8.1+.

clickhouse-cpp versioning
-------------------------

[](#clickhouse-cpp-versioning)

`clickhouse-cpp` is pinned as a git submodule and built into `clickhouse.so`; users do not install `clickhouse-cpp` separately. The extension has its own release version, and each release documents the embedded `clickhouse-cpp` version. `phpinfo()` also reports the embedded C++ client version.

The current submodule pin is `clickhouse-cpp` `v2.6.0`.

To upgrade the C++ client, bump the submodule to an upstream `clickhouse-cpp` tag, run the full PHP matrix, then publish a new extension release. Release source archives must include the initialized submodule so PIE can build without requiring git submodule operations.

For release builds, treat the submodule SHA as part of the extension source. Do not link against a system-installed `clickhouse-cpp` by default; that would make extension behavior depend on distro packaging and local C++ ABI choices.

Release versioning is independent from `clickhouse-cpp`: dependency-only bugfix or security bumps can be patch releases, observable protocol/type/TLS support changes should be minor releases, and PHP API/ABI breaks require a major release.

Build
-----

[](#build)

```
git clone --recursive https://github.com/lucasacoutinho/ext-clickhouse.git
cd ext-clickhouse

phpize
./configure --enable-clickhouse
make
make install
```

If you cloned without `--recursive`, fetch the submodule:

```
git submodule update --init --recursive
```

Add to your `php.ini`:

```
extension=clickhouse
```

Install with PIE
----------------

[](#install-with-pie)

```
pie install lucasacoutinho/ext-clickhouse
```

Usage
-----

[](#usage)

```
use ClickHouse\Driver\Client;
use ClickHouse\Driver\ClientOptions;
use ClickHouse\Driver\Block;
use ClickHouse\Driver\Column;
use ClickHouse\Driver\CompressionMethod;

$client = new Client(new ClientOptions(
    '127.0.0.1',
    9000,
    'default',
    'default',
    '',
    CompressionMethod::LZ4
));

$client->ping();

// DDL
$client->execute('CREATE TABLE IF NOT EXISTS test (id UInt64, name String) ENGINE = Memory');

// Insert
$block = new Block();
$block->appendColumn('id', Column::create('UInt64', [1, 2, 3]));
$block->appendColumn('name', Column::create('String', ['Alice', 'Bob', 'Charlie']));
$client->insert('test', $block);

// Select
$rows = $client->select('SELECT * FROM test');

// Block-by-block streaming
$client->selectByBlock('SELECT * FROM test', function (Block $block): void {
    foreach ($block->toArray() as $row) {
        // process row
    }
});
```

### TLS

[](#tls)

Pass an SSL option array as the 15th `ClientOptions` constructor argument. Defaults are secure when SSL is enabled: system CA locations and SNI are enabled unless explicitly overridden.

```
$client = new Client(new ClientOptions(
    'host.example.com',
    9440,
    'default',
    'default',
    'secret',
    CompressionMethod::LZ4,
    false,
    1,
    5,
    false,
    true,
    5000,
    0,
    0,
    [
        'ca_file' => '/path/to/ca.pem',
        'client_cert' => '/path/to/client.crt',
        'client_key' => '/path/to/client.key',
    ]
));
```

Docker
------

[](#docker)

Pre-built images are available on GitHub Container Registry:

```
docker pull ghcr.io/lucasacoutinho/ext-clickhouse:php8.5-latest
```

Or build locally:

```
docker build --build-arg PHP_VERSION=8.5 -t ext-clickhouse .
```

Running tests
-------------

[](#running-tests)

```
# Requires a running ClickHouse instance
CLICKHOUSE_HOST=127.0.0.1 make test
```

License
-------

[](#license)

[MIT](LICENSE)

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance91

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

58d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b6688cf7dabb10961bde68df0ed41ff2efecec6ae8c37b0feaa1201b100c9681?d=identicon)[kairos-php](/maintainers/kairos-php)

---

Top Contributors

[![lucasacoutinho](https://avatars.githubusercontent.com/u/69213256?v=4)](https://github.com/lucasacoutinho "lucasacoutinho (27 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")

### Embed Badge

![Health badge](/badges/lucasacoutinho-ext-clickhouse/health.svg)

```
[![Health](https://phpackages.com/badges/lucasacoutinho-ext-clickhouse/health.svg)](https://phpackages.com/packages/lucasacoutinho-ext-clickhouse)
```

###  Alternatives

[php-http/cache-plugin

PSR-6 Cache plugin for HTTPlug

25026.1M82](/packages/php-http-cache-plugin)[httpsoft/http-message

Strict and fast implementation of PSR-7 and PSR-17

87965.9k122](/packages/httpsoft-http-message)[serpapi/google-search-results-php

Get Google, Bing, Baidu, Ebay, Yahoo, Yandex, Home depot, Naver, Apple, Duckduckgo, Youtube search results via SerpApi.com

69127.2k](/packages/serpapi-google-search-results-php)[swoft/websocket-server

swoft websocket server component

16135.7k5](/packages/swoft-websocket-server)[thesis/nats

Async (fiber based) client for Nats.

754.4k](/packages/thesis-nats)[jasny/http-signature

Implementation of the IETF HTTP Signatures draft RFC

10104.7k](/packages/jasny-http-signature)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)