Changes for version 0.900004 - 2026-11-08
- First release: the ClickHouse driver for DBIO, over the MySQL wire protocol (server port 9004) through DBD::mysql or DBD::MariaDB.
- Transport
- DBD::mysql is the standard: it connects to a stock server and to ClickHouse Cloud; connect with mysql_enable_utf8mb4 => 1 for character data.
- DBD::MariaDB needs the server to register the character_set_, collation_ and sql_ custom settings prefixes, so it fits servers whose config you control (ADR 0001).
- Both DBDs are the access path of DBIO::ClickHouse::Storage, also under driver_strict. The DSN looks like MySQL's, so a schema pins the storage with the component or use DBIO 'Schema', -ch.
- Storage
- DBIO::ClickHouse::Storage quotes with backticks, pings with SELECT 1 and answers clickhouse_version.
- Inserts fit a database without identity columns: populate is one multi-row INSERT, a UUID primary key marked is_auto_increment is generated client-side, and last_insert_id throws.
- Transactions follow ADR 0003: txn_begin, txn_commit and txn_do run without a transaction and warn once, txn_rollback throws, and a scope guard unwinds without a rollback and says so.
- No transactional DDL, IF [NOT] EXISTS and EXISTS queries are declared; set operations carry an explicit DISTINCT or ALL, rand is rand(), explain answers the plan (see SET OPERATIONS).
- $schema->deploy runs through DBIO::ClickHouse::Deploy, and deployment_statements serves the native DDL layer.
- A string that is not a number and an integer outside its column's type range are refused before they are sent, naming table and column; a value with the byte 0x1A is stored as written.
- The message of a failed statement names the error code, the type, the column, the constraint, the table and the position of a syntax error, and the number of bind values; the values themselves are replaced by *** wherever the engine quotes them: in the sentence of the error, in the statement it quotes, in the Column values of a violated constraint and in the plan of a failed function. This holds for selects, inserts, the multi-row insert of populate, update and delete alike; $dbh->errstr keeps the raw text (ADR 0008).
- SQLMaker
- The resultset attributes final => 1, prewhere => \%cond and limit_by => { rows => $n, by => $cols } render ClickHouse's clauses; SELECT ... FOR UPDATE is not written.
- Mutations
- update and delete on resultsets and rows render as mutations (ALTER TABLE ... UPDATE / DELETE), with mutations_sync => 1 per statement by default (ADR 0005).
- update and delete return -1, row count unknown; a view, a literal SQL source or a join as target and an UPDATE without columns are refused.
- DDL
- DBIO::ClickHouse::DDL maps portable types to Nullable, LowCardinality, Decimal, DateTime64, Date32, UUID, Bool, Enum8/16 and Array; a type spelled as ClickHouse spells it is written as is.
- clickhouse_table({ engine, order_by, primary_key, partition_by, settings }) on a result class; the default is ENGINE = MergeTree ordered by the primary key.
- Canonical index declarations with clickhouse => { type => ... } become data-skipping indexes in CREATE TABLE.
- install_ddl refuses what ClickHouse cannot build, naming table and column: unique constraints, foreign key constraints (declare is_foreign_key_constraint => 0), a non-UUID auto-increment column.
- A source named database.table or database.view is made in that database, and install refuses a missing database; a view follows the views it reads, a cycle is refused.
- Introspect
- DBIO::ClickHouse::Introspect reads system.tables, system.columns and system.data_skipping_indices into the canonical model, with engine, sorting key, partition key and view definitions.
- Diff and Deploy
- The Diff compares in a scratch database on the same server, dropped in every case, and writes IF [NOT] EXISTS wherever ClickHouse parses it, so a re-applied diff changes nothing.
- A change of engine, sorting key, primary key or partition expression is refused with the rebuild steps.
- Skipping indexes, views, the SETTINGS of new tables and removed defaults are diffed; a materialized view is refused by name.
- apply and upgrade are those of DBIO::Deploy::Base: a lossy column change needs allow_destructive, and a narrowing over NULL rows or a NOT NULL column added over rows is refused before the first statement.
- Native export
- DBIO::ClickHouse::Native turns a source and its rows into the columns and row iterator ClickHouse::Encoder takes, and throws for a value it cannot translate truthfully (ADR 0007).
- Async
- The driver is sync-only (ADR 0006); the forked and immediate adapters apply.
- Tests
- DBIO::ClickHouse::Test::Conformance answers core's shared DDL, Diff and Bind case tables offline and against a server, with DBIO::ClickHouse::Test::Schema as the live fixture.
- Live tests run when DBIO_TEST_CLICKHOUSE_DSN is set, each process in a database of its own.
- Dependencies
- Requires DBIO 0.900004, Crypt::URandom, DBI, Try::Tiny, namespace::clean and SQL::Abstract; DBD::mysql and DBD::MariaDB are recommended, ClickHouse::Encoder is suggested and never loaded.
Documentation
Modules
ClickHouse-specific schema management for DBIO
Generate ClickHouse DDL from DBIO Result classes
Single source of ClickHouse DDL statement shape
Deploy and upgrade ClickHouse schemas via test-deploy-and-compare
Compare two introspected ClickHouse models
Diff operations for ClickHouse columns
Diff operations for ClickHouse data-skipping indexes
Diff operations for ClickHouse tables, and the no-silent-rebuild policy
Diff operations for ClickHouse views
Introspect a ClickHouse database via the system.* catalog
Introspect ClickHouse columns via system.columns
Introspect ClickHouse data-skipping indexes via system.data_skipping_indices
Introspect ClickHouse tables and views via system.tables
ClickHouse type-string parser shared by the introspect submodules
Turn DBIO schemas and rows into ClickHouse::Encoder input
ClickHouse-specific Result component for DBIO
ClickHouse-specific SQL generation for DBIO
ClickHouse storage driver for DBIO (MySQL wire protocol)
Scope guard for a storage that has nothing to roll back
ClickHouse-specific test utilities for DBIO
Answers the shared conformance case table for the ClickHouse driver
ClickHouse-native test schema for the DBIO::ClickHouse live suite
Test result class -- the plain MergeTree table with a UUID key
Test result class -- a non-virtual view over the hit table
Test result class -- one column per branch of the DDL type map
Test result class -- partition key, PRIMARY KEY prefix, LowCardinality
Test result class -- a ReplacingMergeTree table for FINAL
Test result class -- the source with no primary key
Shared ClickHouse-specific helper functions for DBIO
`use DBIO -ch` shortcut for the ClickHouse driver