Download the PHP package vaslv/eloquent-clickhouse without Composer

Eloquent ClickHouse

English | Русский

Laravel Eloquent driver for ClickHouse.

Compatibility

Compatibility is covered by automated checks (unit + live-ClickHouse integration tests) for:

• Laravel 12 on PHP 8.2 (lowest supported dependencies), 8.3 and 8.4
• Laravel 13 on PHP 8.3 and 8.4

See .github/workflows/compatibility.yml.

Installation

Configuration

Add a ClickHouse connection to config/database.php:

Example .env values:

TLS

With 'https' => true the server certificate is verified by default (the underlying smi2 client on its own disables verification). Note that the connector's initial ping() goes through an smi2 code path that never verifies certificates; all real queries do.

Usage

Query Builder

Updates and deletes

update() and delete() compile to ClickHouse mutations:

Caveats inherent to ClickHouse:

• Mutations require a MergeTree-family engine. Log-family and Memory tables accept inserts and truncate(), but reject update()/delete()-with-where.
• Mutations are asynchronous by default: a read issued immediately after update()/delete() may see old data. Set 'settings' => ['mutations_sync' => 1] to make them synchronous.
• The HTTP interface reports no affected-row count, so update(), delete(), increment() and decrement() always return 0, and updateOrInsert() returns false on its update branch (the write itself succeeds).
• insertGetId() and upsert() throw: ClickHouse has no auto-increment, RETURNING or ON CONFLICT. Use explicit keys (e.g. UUIDs) and insert(); deduplicate with a ReplacingMergeTree engine where needed.

Migrations

• The blueprint's primary() becomes the MergeTree ORDER BY sorting key; without one the table is created with ORDER BY tuple(). An engine string may carry its own clause: $table->engine('MergeTree ORDER BY (id)').
• hasTable(), hasColumn(), getTables(), getColumns(), getViews(), dropAllTables() (and therefore migrate:fresh) work against system.tables / system.columns.
• Column types map to ClickHouse-native ones (string → String, unsignedBigInteger → UInt64, dateTime($p) → DateTime64($p), boolean → Bool, uuid → UUID, enum → Enum8, ...). nullable() wraps the type in Nullable(...).
• Unsupported concepts fail loudly with a RuntimeException instead of being silently skipped: auto-increment (id()/increments()), indexes, unique/foreign keys, time() columns, nullable columns inside the sorting key.

Array and Map values

PHP arrays compile to ClickHouse-native literals: lists become Array literals, associative arrays become Map construction calls — in inserts, wheres, updates and raw bindings alike:

Raw statements

Notes

• The package registers the clickhouse database driver through its service provider.
• select() returns rows from smi2/phpclickhouse as associative arrays.
• Values are inlined into SQL with ClickHouse-safe escaping (the HTTP interface has no server-side prepared statements). Because values are inlined, they also appear in toSql(), query-log entries and exception messages — keep that in mind for secrets/PII.
• DateTimeInterface values are formatted to whole seconds (Y-m-d H:i:s). ClickHouse's second-precision DateTime column rejects a fractional-seconds string and Carbon always carries microseconds, so sub-second precision is not written even to DateTime64 columns. To store sub-second timestamps, pass a preformatted string (e.g. ->format('Y-m-d H:i:s.u')).
• Read/write connection splitting is supported: a connection config with read/write blocks routes useReadPdo selects to the read host and writes to the write host.
• cursor() streams rows one at a time (smi2 selectGenerator), so it stays memory-bounded on large result sets.
• insertOrIgnore(), upsert() and Postgres-style JSON wheres (whereJsonContains, the -> arrow selector, ...) throw a clear exception rather than emitting SQL ClickHouse cannot run. For JSON, use a raw where with ClickHouse's JSONExtractString / JSONHas.
• Transactions are no-op methods because ClickHouse does not provide transactional behavior like traditional OLTP databases.

Development

A Docker test stack (PHP + live ClickHouse) is included:

Run compatibility checks locally:

To verify the lowest supported Laravel 12 dependency set:

License

MIT