PHPackages                             erikwang2013/clickhouse-php - 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. [Database & ORM](/categories/database)
4. /
5. erikwang2013/clickhouse-php

ActiveLibrary[Database & ORM](/categories/database)

erikwang2013/clickhouse-php
===========================

A full-featured PHP ClickHouse client with HTTP and Native TCP support, query builder, schema builder, migration system, and ORM.

v1.0.2(1mo ago)0101MITPHPPHP >=8.1

Since May 27Pushed 1mo agoCompare

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

READMEChangelog (2)Dependencies (4)Versions (3)Used By (0)

clickhouse-php
==============

[](#clickhouse-php)

PHP ClickHouse 客户端，支持 HTTP 与 Native TCP 双协议，内置查询构建器、Schema Builder、迁移系统和 ORM，深度适配 Laravel、ThinkPHP、Webman、Hyperf。

[English Documentation](README_EN.md)

安装
--

[](#安装)

```
composer require erikwang2013/clickhouse-php
```

快速开始
----

[](#快速开始)

### 独立使用

[](#独立使用)

```
use Erikwang2013\ClickHouse\ClickHouse;
use Erikwang2013\ClickHouse\Client\Manager;

// 配置
$config = [
    'default' => 'clickhouse',
    'connections' => [
        'clickhouse' => [
            'driver'   => 'http',        // http 或 native
            'host'     => 'localhost',
            'port'     => 8123,          // HTTP 端口, Native 用 9000
            'database' => 'default',
            'username' => 'default',
            'password' => '',
            'timeout'  => 30,
        ],
    ],
];

// 初始化
$manager = new Manager($config);
ClickHouse::setManager($manager);

// 查询
$rows = ClickHouse::table('logs')
    ->where('date', '>=', '2024-01-01')
    ->whereIn('level', ['error', 'warn'])
    ->orderBy('timestamp', 'desc')
    ->limit(100)
    ->get();

foreach ($rows as $row) {
    echo $row['message'];
}

// 原生 SQL
$result = ClickHouse::query('SELECT count(*) AS cnt FROM logs WHERE date = ?', ['2024-01-01']);
echo $result->first()['cnt'];

// 聚合
$count = ClickHouse::table('logs')->where('level', 'error')->count();
$avgDuration = ClickHouse::table('logs')->avg('duration');
```

### 插入数据

[](#插入数据)

```
// 单行
ClickHouse::table('logs')->insert([
    'date'      => '2024-01-01',
    'level'     => 'info',
    'message'   => 'hello',
    'duration'  => 12.5,
]);

// 批量
ClickHouse::table('logs')->insert([
    ['date' => '2024-01-01', 'level' => 'info',  'message' => 'a', 'duration' => 1.2],
    ['date' => '2024-01-02', 'level' => 'error', 'message' => 'b', 'duration' => 3.4],
]);
```

### 建表 (Schema Builder)

[](#建表-schema-builder)

```
ClickHouse::schema()->create('logs', function ($table) {
    $table->date('date');
    $table->dateTime('timestamp');
    $table->string('level');
    $table->string('message');
    $table->float64('duration');
    $table->engine('MergeTree')
          ->partitionBy('toYYYYMM(date)')
          ->orderBy(['date', 'timestamp', 'level']);
});

// 删除表
ClickHouse::schema()->drop('logs');

// 修改表
ClickHouse::schema()->alter('logs', function ($table) {
    $table->nullable('source', 'String');
});
```

### 数据迁移

[](#数据迁移)

创建迁移文件（如 `2026_05_27_000000_create_logs_table.php`）：

```
use Erikwang2013\ClickHouse\Migration\Migration;

class CreateLogsTable extends Migration
{
    public function up(): void
    {
        $this->schema->create('logs', function ($table) {
            $table->date('date');
            $table->string('level');
            $table->engine('MergeTree')
                  ->partitionBy('toYYYYMM(date)')
                  ->orderBy(['date', 'level']);
        });
    }

    public function down(): void
    {
        $this->schema->drop('logs');
    }
}
```

运行迁移：

```
use Erikwang2013\ClickHouse\Migration\Migrator;
use Erikwang2013\ClickHouse\Migration\Repository;

$client = ClickHouse::getManager()->connection();
$repository = new Repository($client);
$migrator = new Migrator($client, $repository, '/path/to/migrations');

$migrator->install();   // 创建迁移记录表
$migrator->run();       // 执行待迁移
$migrator->rollback();  // 回滚上一批
$migrator->refresh();   // 回滚后重新执行
```

### ORM

[](#orm)

```
use Erikwang2013\ClickHouse\ORM\Model;

class Log extends Model
{
    protected string $table = 'logs';
    protected string $connection = 'default';
}

// 查询
$logs = Log::where('level', 'error')
    ->orderBy('timestamp', 'desc')
    ->limit(50)
    ->get();

// 查找单条
$log = Log::find(123);

// 聚合
$total = Log::where('date', '>=', '2024-01-01')->count();

// 批量插入
Log::insert([
    ['date' => '2024-01-01', 'level' => 'info'],
    ['date' => '2024-01-02', 'level' => 'error'],
]);
```

### 多连接

[](#多连接)

```
$config = [
    'default' => 'default',
    'connections' => [
        'default' => ['driver' => 'http', 'host' => 'ch1.example.com', 'port' => 8123],
        'analytics' => ['driver' => 'http', 'host' => 'ch2.example.com', 'port' => 8123],
    ],
];

$manager = new Manager($config);

// 使用指定连接
ClickHouse::connection('analytics')->table('events')->get();
ClickHouse::table('events', 'analytics')->get();
```

框架集成
----

[](#框架集成)

### Laravel

[](#laravel)

配置文件自动发布，Composer 自动发现 ServiceProvider。

```
php artisan vendor:publish --tag=clickhouse-config
```

```
use Erikwang2013\ClickHouse\Laravel\Facades\ClickHouse;

ClickHouse::table('logs')->where('level', 'error')->get();
ClickHouse::connection('native')->select('SELECT * FROM logs LIMIT 10');
```

Artisan 命令：

```
php artisan clickhouse:table-list
php artisan clickhouse:migration:install
php artisan clickhouse:migration:run
```

### ThinkPHP

[](#thinkphp)

在 `app/service.php` 中注册服务：

```
return [
    \Erikwang2013\ClickHouse\ThinkPHP\ClickHouseService::class,
];
```

```
use think\facade\ClickHouse;

ClickHouse::table('logs')->get();
```

```
php think clickhouse:table-list
```

### Webman

[](#webman)

Webman 自动加载插件配置，无需手动配置。

```
use Erikwang2013\ClickHouse\Webman\ClickHouse;

ClickHouse::table('logs')->where('level', 'error')->get();
```

### Hyperf

[](#hyperf)

通过 `ConfigProvider` 自动发现，支持依赖注入和协程连接池。

```
php bin/hyperf.php vendor:publish erikwang2013/clickhouse-php
```

```
use Erikwang2013\ClickHouse\Hyperf\ClickHouseConnection;

class LogController
{
    public function __construct(
        private ClickHouseConnection $clickhouse
    ) {}

    public function index()
    {
        return $this->clickhouse->table('logs')->get();
    }
}
```

查询构建器参考
-------

[](#查询构建器参考)

方法说明`table($name)` / `from($name)`指定表名`select([...])` / `selectRaw($expr)`SELECT 列`where($col, $op, $val)`条件 (2 参数时 `$op` 默认 `=`)`orWhere($col, $op, $val)`OR 条件`whereIn($col, $arr)` / `whereNotIn($col, $arr)`IN / NOT IN`whereBetween($col, [$min, $max])`BETWEEN`whereNull($col)` / `whereNotNull($col)`IS NULL / IS NOT NULL`whereRaw($sql)`原生 WHERE`orderBy($col, $dir)`排序 (默认 ASC)`groupBy(...$cols)`分组`limit($n)` / `offset($n)`分页`count()` / `sum($col)` / `avg($col)` / `min($col)` / `max($col)`聚合`insert($data)`插入 (单行或批量)`delete()`删除`get()`执行查询，返回 Result`first()`返回第一条`toSql()`获取生成的 SQLSchema 列类型
----------

[](#schema-列类型)

方法ClickHouse 类型`string($name)`String`fixedString($name, $len)`FixedString(N)`int8/16/32/64($name)`Int8/16/32/64`uint8/16/32/64($name)`UInt8/16/32/64`float32($name)` / `float64($name)`Float32 / Float64`decimal($name, $p, $s)`Decimal(P, S)`date($name)`Date`dateTime($name)`DateTime`dateTime64($name, $p)`DateTime64(P)`uuid($name)`UUID`bool($name)`Bool`array($name, $type)`Array(T)`nullable($name, $type)`Nullable(T)`lowCardinality($name, $type)`LowCardinality(T)配置参考
----

[](#配置参考)

```
[
    'default' => 'clickhouse',
    'connections' => [
        'clickhouse' => [
            'driver'   => 'http',     // http | native
            'host'     => 'localhost',
            'port'     => 8123,       // HTTP 8123, Native 9000
            'database' => 'default',
            'username' => 'default',
            'password' => '',
            'timeout'  => 30,
        ],
    ],
    'pool' => [
        'min_connections'    => 2,
        'max_connections'    => 16,
        'connection_timeout' => 5.0,
    ],
    'query_log' => false,
];
```

环境变量
----

[](#环境变量)

变量默认值说明`CLICKHOUSE_HOST`localhost主机地址`CLICKHOUSE_PORT`8123HTTP 端口`CLICKHOUSE_DB`default数据库名`CLICKHOUSE_USER`default用户名`CLICKHOUSE_PASS`—密码`CLICKHOUSE_TIMEOUT`30连接超时(秒)`CLICKHOUSE_DRIVER`http驱动类型`CLICKHOUSE_POOL_MIN`2最小连接数`CLICKHOUSE_POOL_MAX`16最大连接数异常处理
----

[](#异常处理)

```
use Erikwang2013\ClickHouse\Exceptions\{
    ClickHouseException,
    ConnectionException,
    QueryException,
    TimeoutException,
    PoolException,
};

try {
    ClickHouse::table('logs')->get();
} catch (ConnectionException | TimeoutException $e) {
    // 连接或超时问题
} catch (QueryException $e) {
    echo $e->getMessage();
    echo $e->getSql();      // 原始 SQL
} catch (ClickHouseException $e) {
    // 其他异常
}
```

许可证
---

[](#许可证)

MIT License. Copyright (c) 2026 erik  —

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance88

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

2

Last Release

58d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/9014941?v=4)[erik](/maintainers/erikwang2013)[@erikwang2013](https://github.com/erikwang2013)

---

Top Contributors

[![erikwang2013](https://avatars.githubusercontent.com/u/9014941?v=4)](https://github.com/erikwang2013 "erikwang2013 (22 commits)")

---

Tags

phpclientdatabaseclickhouse

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/erikwang2013-clickhouse-php/health.svg)

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

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.5k](/packages/laravel-framework)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[leantime/leantime

Open source project management system for non-project managers. Simple like Trello, powerful like Jira. Built with neurodiversity in mind.

10.2k4.0k](/packages/leantime-leantime)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19566.0M1.8k](/packages/drupal-core)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k46](/packages/civicrm-civicrm-core)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.5M7](/packages/avalara-avataxclient)

PHPackages © 2026

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