view release on metacpan or  search on metacpan

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

so allocating callbacks is essentially free after warm-up. The
implication: avoid wrapping the connection in heavy wrappers that
clone the connection per call - there is no per-call setup cost worth
amortising away.

=back

=head1 ARCHITECTURE

The client is a single state machine driven by an L<EV> event loop. Each
connection holds: a TCP fd (non-blocking), a send buffer, a receive
buffer, a callback queue (next-in-line per protocol), and a pending
send queue (buffered before connect).

State transitions:

    Connect TCP --> [TLS handshake] --> [Native ServerHello]
        --> Connected --> { dispatch from send_queue;
                            parse response; deliver via cb_queue }

The connect_timeout timer covers all three pre-Connected stages.
auto_reconnect re-runs the chain via C<schedule_reconnect>.

Two key invariants:

=over 4

=item *

Native protocol is strictly request/response. Only one query is
in-flight per connection at a time. C<insert_streamer> serialises
batches against this constraint.

=item *

C<callback_depth> guards against C<self> being freed mid-callback.
Every callback dispatch increments it; C<check_destroyed> defers the
final C<Safefree> until depth returns to zero.

=back

For deeper detail (state-machine table, queue semantics) see C<CLAUDE.md>
in the source distribution.

=head1 TYPES

Per-column wire format and Perl-side gotchas. All numeric types
round-trip stable raw values by default; opt into string forms via
C<decode_datetime>, C<decode_decimal>, C<decode_enum>.

=over 4

=item Integers

Int8..Int64 / UInt8..UInt64: native Perl IV/UV. Int128/UInt128/Int256/UInt256
return decimal string representations on platforms with C<__int128> (Int128/UInt128)
or always for the 256-bit forms.

=item Floats

Float32/Float64 round-trip exactly within IEEE-754 limits. C<NaN>/C<+Inf>/
C<-Inf> are preserved.

=item BFloat16

Top 16 bits of a Float32. Encoded by truncation; decoded by zero-extension.
Suitable for ML feature columns; not for accounting.

=item Decimal32/64/128

Decoded as IV (raw integer) or NV (scaled to N decimal digits if
C<decode_decimal =E<gt> 1>). Decimal128 over very long precision may lose
trailing digits in the NV form; pass C<decode_decimal =E<gt> 0> and divide
yourself with L<Math::BigInt> for exact arithmetic.

=item Decimal256

Returns raw 32 LE bytes. Decode with L<Math::BigInt> (see
C<eg/decimal_bigmath.pl>).

=item Date / Date32 / DateTime / DateTime64

Default: integer (days since epoch / Unix seconds). With C<decode_datetime>:
C<YYYY-MM-DD> or C<YYYY-MM-DD HH:MM:SS> or C<YYYY-MM-DD HH:MM:SS.ffffff>.
DateTime carries a timezone string; the formatted output uses it.

=item Bool

Decoded as 0/1. Encoded from any truthy/falsy SV. ClickHouse stores
internally as UInt8 0/1.

=item String / FixedString

Bytes-in, bytes-out. No UTF-8 transformation.

=item UUID

Canonical hex form C<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx>. Encode
accepts the same.

=item IPv4 / IPv6

Dotted-quad / canonical IPv6 strings.

=item Enum8 / Enum16

Default: integer code. With C<decode_enum =E<gt> 1>: label string.

=item Nullable(T)

C<undef> in Perl maps to null; otherwise the inner type's encoding.

=item Array(T)

Perl arrayref of inner-type values.

=item Tuple(T1, T2, ...)

Perl arrayref ordered as the type declaration. Named tuples
(C<Tuple(a Int32, b String)>) are still arrayref-positional;
parse the name from C<column_types> if you need it.