NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #986 most downloaded on Packagist
PHP ClickHouse Client
Latest stable
1.26.1106
Last release 16 days ago
06 Nov 2026
Release timing varies
gaps range from 2 weeks to 1.2 years
Most releases are documented
notes for 47 of 54 stable releases
Nothing withdrawn
no release was ever pulled
10 years old
54 releases · first in 2016
Drag across the ruler to compare, or tap a release to open it.
Escaping fixes in insert and binding paths — upgrading is recommended. Values without special characters produce byte-identical SQL:
insert() / insertAssocBulk() — column names (and the auto-quoted table name) now escape ` and \ inside backticks, so a column name taken from user data (e.g. array keys in insertAssocBulk()) can no longer break out of the identifierStringType, Date*, UUID, IPv4/6, enums, any Stringable — are escaped like plain strings in INSERT and CSV rows; objects inside TupleType / MapType are formatted via ValueFormatterisExists() uses bindings instead of string concatenationValueFormatter escapes the ->value of backed enums and other objects exposing it (previously returned raw — e.g. a json_decode() stdClass could inject SQL)Expression\Func\UUIDStringToNum escapes its argumentverbose(false) no longer enables verbose mode — the flag was ignored, so calling it turned on curl verbose output (request headers, including X-ClickHouse-Key, on stderr)@psalm-taint-sink / @psalm-taint-escape annotations; additionally the entry points that intentionally bypass escaping (UInt64, Int64, Decimal, Boolean, UUID, IPv4, IPv6, Date32, DateTime64 ::fromString() and Expression\Raw) are marked as SQL sinks — pass trusted data only$value (other than Type/Expression) bound as :param is now quoted and escaped like a scalar: 'object_value' instead of raw object_value. Integer-backed enums are unchanged (3)status = active → UNKNOWN_IDENTIFIER); arrays of enums crashed in Bindings; native params (selectWithParams() etc.) crashed with could not be converted to string, and string enums inside Array(...) params were unquotedINSERT (#284, @mjpvandenberg; #283) — Array(Tuple(...)) and Array(Map(...)) failed with Cannot parse expression; tuple/map literals are now emitted unquoted in the Insert preset, top-level tuples in CSV stay enclosedselectGenerator() / streamRead() with array native params (#278, @sidz) — {ids:Array(UInt32)} produced param_ids[0]=… instead of param_ids=[1,2] (UNKNOWN_QUERY_PARAMETER)FormatLine::TSV escapes backslashes — C:\new was turned into a newline, a trailing \ swallowed the delimiterdropPartition() / truncateTable() — placeholder regression from the typo fix (#277) caught in review and fixed before merge; now covered by testscomposer update locally (composer.lock is not committed)8.6.0-dev) and runs with continue-on-errorInjectionRegressionTest, EnumBindingsTest, TupleMapArrayInsertTest, DropPartitionTest, ErrorMessagesTest; every executable src/ line changed in this release is coveredsrc/, tests/ and docs (#275, #276, #277, @peter279k); clearer exception messages ('host is not set', 'progressFunction is not callable' check removed as unreachable).gitattributes export-ignore for docs/, example/, phpunit-*.xml, *.neon (#279, @sidz) — smaller Composer dist packageYour coding agent can read these notes before it upgrades. Set up the MCP server →
Minimum PHP raised to 8.1 — composer.json now requires php: ^8.1 and the CI matrix drops 8.0. PHP 8.0 users should pin 1.26.4 (last 8.0-compatible rel
composer.json now requires php: ^8.1 and the CI matrix drops 8.0. PHP 8.0 users should pin 1.26.4 (last 8.0-compatible release); the typed >= 1.24.406 line already targets 8.1+StringType (PHP reserves String), FixedString(N) with strict byte-length validation, Date, DateTime (with optional non-mutating timezone conversion), Enum8, Enum16. All implement the new StringableType interface: unlike legacy Type objects, their values are escaped by ValueFormatter, bindings, and native parametersInt8–Int256, UInt8–UInt256, Float32/Float64, Decimal32–Decimal256 via the new ScalarNumericType interface (Bool maps to the existing Boolean class). fromString() validates input — integers require ^-?\d+$, floats/decimals require is_numeric() — closing an SQL-injection vector for untrusted input, since Type values are interpolated into SQL unescapedDatabaseException::getServerVersion() and getServerStackTrace() (populate with per-query ['stacktrace' => 1]); reworked error-response parsing in Statement. The server stack trace is kept out of getMessage() — it is available only via the dedicated gettertests/Type/Ieee754MantissaTest.php, 31 cases) — significand limits and overflow collapse for Float32 (2^24), Float64 (2^53), BFloat16 (2^8, CH 24.11+); 0.1 + 0.2 != 0.3 vs exact Decimal arithmetic; inf/nan → null in JSON; scale-0 truncation toward zero; Decimal arriving as an unquoted JSON number on every supported server; the json_decode() precision trap for >16-digit decimals (exact reads need toString())clickhouse-26-9 (26.9.1.1629, port 8125), phpunit-ch269.xml, CI job PHP 8.1–8.4 × CH 26.9. Suites for 21.9 / 26.3 / 26.9 run separatelymax_execution_time is visible to getSetting() without touching global settingsREADME.md, doc/types.md, and the Pages site now link the IEEE 754 standard and the ClickHouse Float reference, with a verified 0.1 + 0.2 != 0.3 example and the exact-Decimal counterparttodo.md translated to English (#268, @sander-hash)README.md and the Pages site (docs/index.md).gitignore now covers .DS_Store, .idea/, vim swap files, and local ClickHouse data directoriesDistributed DDL (`ON CLUSTER`) formatting reworked (#241, #263, #262) — Http::prepareWrite() no longer appends FORMAT JSON to the SQL of ON CLUSTER qu
ON CLUSTER) formatting reworked (#241, #263, #262) — Http::prepareWrite() no longer appends FORMAT JSON to the SQL of ON CLUSTER queries. Instead the response format is requested via the default_format=JSON query setting:
CREATE USER / GRANT / ALTER ... ON CLUSTER no longer fail with SYNTAX_ERROR from a stray FORMAT JSON (#241)CREATE / ALTER ... ON CLUSTER results are now parseable JSON again — no more Can't find meta when reading the per-host execution status (#263)ON CLUSTER substring inside INSERT data (e.g. 'REGION CLUSTER') is no longer mistaken for the keyword — \b word boundaries match the real keyword only (#262)Statement::hasErrorClickhouse() now confirms a tail-regex match with json_validate() (PHP 8.3+) before flagging an error, so valid JSON whose data legitimately contains ClickHouse exception text is not reported as a failure (@jradtilbrook)tests/ClickHouse26/OnClusterTest.php — distributed DDL regression tests (CREATE / ALTER / CREATE USER ... ON CLUSTER); skips gracefully when no Keeper/ZooKeeper backend is configuredtests/clickhouse-latest-config/keeper.xml, mounted in docker-compose.yaml and copied in CI) so the single-node default cluster can execute ON CLUSTER queriestestInsertWithOnClusterInData added to both CH 21 and CH 26 client tests (#262)FORMAT JSON in the query when inserting a record (superseded by the default_format fix)Escape single quotes and backslashes in scalar string native params (#258, #259) — convertParamValue() now escapes \ → \\ and ' → \' for scalar String
convertParamValue() now escapes \ → \\ and ' → \' for scalar String params in selectWithParams() / writeWithParams(). Previously strings like hello\ caused CANNOT_PARSE_ESCAPE_SEQUENCE in ClickHouse (@sander-hash, @tom-on-the-internet)writeWithParams with backslashCANNOT_PARSE_ESCAPE_SEQUENCECorrectly encode arrays for native param binding (#257) — convertParamValue() now produces ClickHouse-compatible array literals ['foo','bar'] (single
convertParamValue() now produces ClickHouse-compatible array literals ['foo','bar'] (single quotes) instead of JSON format ["foo","bar"]. Previously any Array(String) parameter in selectWithParams() / writeWithParams() failed with a parse error (@sander-hash)' or \ are now properly escaped (e.g. "it's" → 'it\'s'), preventing query errors and array-element injectionArray(UInt32), Array(String), empty arrays, strings with single quotes, strings with backslashes, and injection attemptsFix bindParams() TypeError with numeric keys (#256) — bindParams() now casts integer array keys to string before passing to bindParam(string $column),
bindParams() now casts integer array keys to string before passing to bindParam(string $column), restoring backward compatibility with numerically-indexed arrays. Affected downstream packages like phpclickhouse-laravel (@yehezkel-fullpath)testConnectTimeout, testStreamInsert, testStreamInsertFormatJSONEachRow marked @group flaky and excluded via PHPUnit config. Run separately with ./vendor/bin/phpunit --group flakytestBindParamsWithNumericKeys, testBindParamsWithMixedKeys covering #256 regressionBindings::bindParam() rejects integer keys`readWithParams()` (#254) — stream query results with native ClickHouse typed parameters ({name:Type} syntax), combining server-side parameter binding
readWithParams() (#254) — stream query results with native ClickHouse typed parameters ({name:Type} syntax), combining server-side parameter binding with streaming output (@sander-hash)Stringable for consistency (@sander-hash)readWithParams() in native-params, streaming, and per-query-settings guidesBoolean Type (#251) — new ClickHouseDB\Type\Boolean class with fromString(), fromBool(), getValue(), __toString() (@sander-hash)
WARNING : PHP 8.1+
ClickHouseDB\Type\Boolean class with fromString(), fromBool(), getValue(), __toString() (@sander-hash)Degeneration, IStream, Type) unchanged for backward compatibilitysecure-scan.md. All clean: no backdoors, exfiltration, or obfuscation foundValueFormatterTest (28) — SQL escaping, types, DateTimeInterface, ExpressionStrictQuoteLineTest (32) — CSV/TSV/Insert formatting, encodeStringSettingsTest (24) — get/set/is, sessions, timeouts, readonlyWriteToFileTest (15) — file validation, formats, gzipTypesTest (26+5) — UInt64, DateTime64, MapType, TupleType, Boolean and moreBindingsUnitTest (16) — compile_binds, Conditions {if}/{else}CurlerRequestResponseTest (35) — headers, auth, URL, JSON, dump## 2026-04-04 [Release 1.26.4] Many changes see change.log
Many changes see change.log
Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com
Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com
### 2025-01-14 [Release 1.6.0] * Support php 8 * And some pr & fixes
fix(#202): Fix converting boolean when inserting into int and fix(#194): Fix unexpected readonly mode with specific string in query #203
fix(#202): Fix converting boolean when inserting into int and fix(#194): Fix unexpected readonly mode with specific string in query #203
SELECT number+{num_num:UInt8} as numbe_r, {xpx1:UInt32} as xpx1,{zoza:String} as zoza FROM system.numbers LIMIT 6
BREAKING CHANGES
SELECT number+{num_num:UInt8} as numbe_r, {xpx1:UInt32} as xpx1,{zoza:String} as zoza FROM system.numbers LIMIT 6
Change exceptionCode in Clickhouse version 22.8.3.13 (official build) #180
Change exceptionCode in Clickhouse version 22.8.3.13 (official build) #180
Fix Docker for tests, Change the correct Docker image name #177
Some type fix
Fix types: max_execution_time & setConnectTimeOut, undo: Support floats in timeout and connect_timeout #173
add mbstring to composer require #183
fixed progressFunction #182
Add allow_plugins setting since Composer 2.2.x #178
Re upload 1.5.0 - hot fix types error
Return type of ClickHouseDB\Statement::current() should either be compatible with Iterator::current() #170
Migrate setTimeout from Float to Int
ping(true) throw TransportException if can`t connect/ping
Fix: prevent enable_http_compression parameter from being overridden #164
Fixed issue with non-empty raw data processing during init() on every fetchRow() and fetchOne() call - PR #161
### 2021-01-19 [Release 1.4.1] * Add support php 7.3 & php 8
Nothing published for this version
Add two new types of authentication #139 Fixed typo in streamRead exception text #140 fix the exception(multi-statement not allow) when sql end with '
Add two new types of authentication #139 Fixed typo in streamRead exception text #140 fix the exception(multi-statement not allow) when sql end with ';' #138 Added more debug info for empty response with error #135
### 2020-02-03 [Release 1.3.9] * #134 Enhancement: Add a new exception to be able to distinguish that ClickHouse is not available.
Fix error : The error of array saving #127
dropOldPartitions### 2019-09-20 [Release 1.3.7] * #125 WriteToFile: support for JSONEachRow format
Use X-ClickHouse-User by headers
Fix phpStan warnings in getConnectTimeOut() & max_execution_time()
Nothing published for this version
fix clickhouse release 19.5.2.6 error parsing #117
fix: add CSVWithNames to supported formats #107
Pull request #94 from simPod: Uint64 values
Fix #91 ,Does not work inserting with the database name in the table
Escape values in arrays, pull request #87 from simPod/fix-escape
* Connection without port
New $client->getServerVersion()
$client->getServerVersion()$client->ping()include.php - ClickHouseException before exceptionsinterface ClickHouseExceptionNothing published for this version
Bindings wrong work - fix `php $keys=[ 'A'=>'{B}', 'B'=>':C', 'C'=>123, 'Z'=>[':C',':B',':C'] ]; $this->client->selectAsync('{A} :Z', $keys)->sql() //
Bindings wrong work - fix
$keys=[
'A'=>'{B}',
'B'=>':C',
'C'=>123,
'Z'=>[':C',':B',':C']
];
$this->client->selectAsync('{A} :Z', $keys)->sql() // == "123 ':C',':B',':C' FORMAT JSON",
Bindings wrong work - fix `php $keys=[ 'A'=>'{B}', 'B'=>':C', 'C'=>123, 'Z'=>[':C',':B',':C'] ]; $this->client->selectAsync('{A} :Z', $keys)->sql() //
Bindings wrong work - fix
$keys=[
'A'=>'{B}',
'B'=>':C',
'C'=>123,
'Z'=>[':C',':B',':C']
];
$this->client->selectAsync('{A} :Z', $keys)->sql() // == "123 ':C',':B',':C' FORMAT JSON",
$client->getServerUptime() Returns the server's uptime in seconds.
2018-07-02 [Release 1.1.0]
New:
$client->getServerUptime() Returns the server's uptime in seconds.$client->getServerSystemSettings() Read system.settings table and return array$client->streamWrite() function$client->streamRead() functionWarning:
HttpCompression set trueStreamInsert classFix:
rawData() result in JSONCompact & JSONEachRow format1.0.1 Do not convert int parameters in array to string in Bindings pull 67
1.0.1 Do not convert int parameters in array to string in Bindings pull 67
Nothing published for this version
+ progressFunction() + Escape values
Nothing published for this version
fix timeout error and add test 2016-10-23
2016-10-25 Release 0.16.10
fix timeout error and add test 2016-10-23
client->setTimeout($seconds) cluster->clientLike($cluster,$ip_addr_like) Delete all migration code from driver, move to https://github.com/smi2/phpMigrationsClickhouse
- exception on error write
- init
0.18.06.19 * Add DateTimeInterface for Bind * Fix phpDocs in code
0.18.06.19
0.18.06.18 Try fix problem with php 5.6
0.18.06.18 Try fix problem with php 5.6
Nothing published for this version
!Move class in namespace! !Check your code!
0.18.05.09
WARN!!!
!Move class in namespace! !Check your code!
Move \ClickHouseDB\WhereInFile to \ClickHouseDB\Query\WhereInFile
Move \ClickHouseDB\QueryException to \ClickHouseDB\Exception\QueryException
Move \ClickHouseDB\DatabaseException to ClickHouseDB\Exception\DatabaseException
Move \ClickHouseDB\FormatLine to \ClickHouseDB\Quote\FormatLine
Move \ClickHouseDB\WriteToFile to ClickHouseDB\Query\WriteToFile
Move \Curler\Request to \ClickHouseDB\Transport\CurlerRequest
Move \Curler\CurlerRolling to \ClickHouseDB\Transport\CurlerRolling
Nothing published for this version
Delete all migration code from driver
See readme, change log
New:
Version/Release names: [ zero dot year dot month]
sizebytessee example/exam16_custom_degeneration.php
One column per quarter.