EV::ClickHouse

Async ClickHouse client for Perl using the EV event loop.

Implements both the ClickHouse HTTP and native TCP protocols directly in XS — no external ClickHouse client library dependency.

Features

• Async connect, query, insert via HTTP protocol (port 8123)
• Native TCP protocol (port 9000) with binary column-oriented data
• TabSeparated format parser with NULL/escape handling
• Gzip compression (HTTP) and LZ4 compression (native)
• Session management via session_id (HTTP)
• TLS/SSL support via OpenSSL (with tls_skip_verify for self-signed certs)
• Connection URI parsing (clickhouse[+native]://user:pass@host:port/db)
• Per-query and connection-level ClickHouse settings
• Parameterized queries (params => { name => value })
• Auto-reconnect with exponential backoff
• Keepalive ping for idle native connections
• Graceful drain callback, query cancel, skip_pending
• Streaming results via on_data per-block callback (native)
• Raw HTTP response mode (returns body unparsed for CSV/JSON/Parquet)
• Opt-in decode of Date/DateTime, Decimal, Enum columns
• Named-rows mode (rows as hashrefs keyed by column name)
• Per-query query_timeout with automatic cancellation
• Insert from TSV string or arrayref of arrayrefs
• 30+ ClickHouse types: Int/UInt 8–256, Float, Bool, String, FixedString, Date/Date32/DateTime/DateTime64 with timezones, Decimal32/64/128, UUID, IPv4, IPv6, Enum8/16, Nullable, Array, Tuple, Map, LowCardinality (with cross-block dictionary), SimpleAggregateFunction, Nested, Nothing

Synopsis

use EV;
use EV::ClickHouse;

my $ch;
$ch = EV::ClickHouse->new(
    host       => '127.0.0.1',
    port       => 8123,
    on_connect => sub {
        $ch->query("select * from system.one format TabSeparated", sub {
            my ($rows, $err) = @_;
            die $err if $err;
            print join(", ", @{$rows->[0]}), "\n";
            EV::break;
        });
    },
    on_error => sub { die $_[0] },
);

EV::run;

Build

perl Makefile.PL
make
make test   # needs ClickHouse running

Set TEST_CLICKHOUSE_HOST and TEST_CLICKHOUSE_PORT (HTTP) or TEST_CLICKHOUSE_NATIVE_PORT (native) environment variables if ClickHouse is not on 127.0.0.1:8123/9000.

Dependencies

• EV (Perl module)
• zlib (-lz)
• OpenSSL (optional, for TLS)
• liblz4 (optional, for native protocol compression)

License

Same terms as Perl itself.