/ 
DBIO-ClickHouse-0.900004
/ DBIO::ClickHouse::Introspect::Tables

NAME

DBIO::ClickHouse::Introspect::Tables - Introspect ClickHouse tables and views via system.tables

VERSION

version 0.900004

DESCRIPTION

Fetches ClickHouse table and view metadata from system.tables, scoped to one database (currentDatabase() by default).

system.tables is used rather than information_schema.tables on purpose: information_schema is a MySQL-shaped compatibility view that has no column for the engine, the sorting key or the partition key -- exactly the three things a ClickHouse CREATE TABLE cannot be rebuilt without. See docs/adr/0001-mysql-wire-protocol-transport.md: the wire is MySQL's, the catalog is not.

What is captured, and why

Beyond the canonical table_name / kind, every row carries the MergeTree metadata the diff layer needs to tell "the same table" from "a table that needs recreating":

  • engine -- the bare engine name (MergeTree, ReplacingMergeTree).

  • engine_expression -- the engine with its arguments, extracted from engine_full. system.tables.engine drops them, so a ReplacingMergeTree(version) table reports plain ReplacingMergeTree there and the version column would be lost. This is the value that maps back to DBIO::ClickHouse::Result's clickhouse_table->{engine}.

  • sorting_key / primary_key / partition_key -- the raw expression strings as the server renders them, plus *_entries, the same lists split on top-level commas.

  • primary_key_columns -- the primary_key_entries that are bare column names, in order. ClickHouse has no primary-key constraint; the MergeTree key is the primary key, and it may contain expressions (cityHash64(id)) that are not columns at all. Only the bare identifiers can answer "is this column part of the primary key", which is what "table_pk_info" in DBIO::Introspect::Base asks.

sorting_key and primary_key are equal whenever the table did not declare a separate PRIMARY KEY prefix -- ClickHouse fills the latter in from the former. The caller decides whether that is worth emitting.

METHODS

fetch

my $tables = DBIO::ClickHouse::Introspect::Tables->fetch($dbh);
my $tables = DBIO::ClickHouse::Introspect::Tables->fetch($dbh, $database);

Returns a hashref keyed by table name. Each value is a hashref with keys: table_name, kind (table or view), database, engine, engine_full, engine_expression, sorting_key, sorting_key_entries, primary_key, primary_key_entries, primary_key_columns, partition_key, partition_key_entries, sampling_key, comment, and for a view definition, its SELECT as the server holds it (create_table_query without the statement head; the server writes the database into the names it qualifies).

When $database is undef the query is scoped to currentDatabase().

SEE ALSO

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.