EV-ClickHouse

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    and the connection is torn down so no subsequent query can slip past
    the cap on the same socket. With `auto_reconnect` the link is
    re-established afterwards (the cap still applies to every response).
    `0` (default) keeps the historical no-cap behaviour (still bounded
    internally by a hard 128 MB ceiling on compressed paths). Recommended
    in production when the schema is constrained and you want a hard upper
    bound (e.g. `128 * 1024 * 1024` for 128 MB).

- http\_basic\_auth => 0 | 1

    HTTP only. When set, send credentials as
    `Authorization: Basic base64(user:password)` instead of the default
    `X-ClickHouse-User` / `X-ClickHouse-Key` header pair. Use this when
    the connection passes through an HTTP gateway (nginx, Envoy, ...) that
    strips the X-ClickHouse-\* headers but forwards Basic auth verbatim.
    Default: `0`.

- auto\_reconnect => 0 | 1

    Reconnect automatically on connection loss. Default: `0`. When enabled,
    queued (unsent) queries are preserved across reconnects; in-flight queries

README.md  view on Meta::CPAN

    soon as the parser has it, and rows are not accumulated across blocks.
    (Rows within a block are still decoded to Perl values first, so
    per-row decode work is the same - the saving is the accumulation.)
    `iterate` is a synchronous-feeling pull wrapper around
    the same machinery - useful when the surrounding code is procedural
    (ETL scripts, exporters) and a callback shape doesn't fit. Both are
    native-only.

- Connection in front of nginx / reverse proxy strips X-ClickHouse-\* headers

    Pass `http_basic_auth => 1` to send the credentials as
    `Authorization: Basic ...` instead. Most HTTP gateways forward
    Authorization verbatim while filtering proprietary headers.

# TUNING

- Native vs HTTP

    Native (port 9000) is typically 1.5-3x faster for select-of-many-rows
    because rows ship as binary columns instead of TSV text. Inserts are
    usually server-bound and land within noise of each other on either

eg/auth_proxy.pl  view on Meta::CPAN

#!/usr/bin/env perl
# HTTP basic auth behind a reverse proxy. Many gateway setups
# (nginx, Envoy, k8s ingress) strip the proprietary X-ClickHouse-User
# and X-ClickHouse-Key headers but forward Authorization verbatim.
# Pass http_basic_auth => 1 to send credentials as
# `Authorization: Basic base64(user:password)` instead.
#
# Pair with `auth_request` / `proxy_pass` in nginx, JWT middleware
# in Envoy, etc. — the client side is the same regardless.
use strict;
use warnings;
use EV;
use EV::ClickHouse;

my $host = $ENV{CLICKHOUSE_HOST} // '127.0.0.1';

lib/EV/ClickHouse.pm  view on Meta::CPAN

and the connection is torn down so no subsequent query can slip past
the cap on the same socket. With C<auto_reconnect> the link is
re-established afterwards (the cap still applies to every response).
C<0> (default) keeps the historical no-cap behaviour (still bounded
internally by a hard 128 MB ceiling on compressed paths). Recommended
in production when the schema is constrained and you want a hard upper
bound (e.g. C<128 * 1024 * 1024> for 128 MB).

=item http_basic_auth => 0 | 1

HTTP only. When set, send credentials as
C<Authorization: Basic base64(user:password)> instead of the default
C<X-ClickHouse-User> / C<X-ClickHouse-Key> header pair. Use this when
the connection passes through an HTTP gateway (nginx, Envoy, ...) that
strips the X-ClickHouse-* headers but forwards Basic auth verbatim.
Default: C<0>.

=item auto_reconnect => 0 | 1

Reconnect automatically on connection loss. Default: C<0>. When enabled,
queued (unsent) queries are preserved across reconnects; in-flight queries

lib/EV/ClickHouse.pm  view on Meta::CPAN

soon as the parser has it, and rows are not accumulated across blocks.
(Rows within a block are still decoded to Perl values first, so
per-row decode work is the same - the saving is the accumulation.)
C<iterate> is a synchronous-feeling pull wrapper around
the same machinery - useful when the surrounding code is procedural
(ETL scripts, exporters) and a callback shape doesn't fit. Both are
native-only.

=item Connection in front of nginx / reverse proxy strips X-ClickHouse-* headers

Pass C<<< http_basic_auth =E<gt> 1 >>> to send the credentials as
C<Authorization: Basic ...> instead. Most HTTP gateways forward
Authorization verbatim while filtering proprietary headers.

=back

=head1 TUNING

=over 4

=item Native vs HTTP

xs/proto_native_parse.c  view on Meta::CPAN

            Safefree(errmsg);
            return;
        }

        if (rc == 5) {
            /* Server exception — a normal query error with its bytes
             * consumed, so the stream stays in sync: deliver to the
             * query callback and pipeline the next query. */
            if (self->native_state == NATIVE_WAIT_HELLO) {
                /* The server rejected the handshake itself (e.g. wrong
                 * credentials) — fail fast with the real text, to
                 * on_error and to any pre-connect queued queries. No
                 * reconnect: retrying a rejected handshake just spins. */
                teardown_io_error(self, errmsg, errmsg);
                Safefree(errmsg);
                return;
            }
            stop_timing(self);

            CLEAR_SV(self->native_rows);
            CLEAR_INSERT(self);