# ch_driver v0.1.0 - Table of Contents

> DBConnection driver speaking ClickHouse's native TCP protocol, including its LZ4/CityHash compression NIF and compressed-block wire envelope.

## Modules

- [ChDriver](ChDriver.md): Public API for the ClickHouse native-protocol driver: a `DBConnection`
pool wrapping `ChDriver.Connection`'s TCP handshake and query encoding.
- [ChDriver.Codec](ChDriver.Codec.md): LZ4 block compression and CityHash v1.0.2 checksums for ClickHouse's
native protocol block framing.
- [ChDriver.Connection](ChDriver.Connection.md): Socket-level connection setup and query execution for ClickHouse's
native TCP protocol.
- [ChDriver.DBConnection](ChDriver.DBConnection.md): `DBConnection` behaviour implementation wrapping `ChDriver.Connection`'s
synchronous request/response socket so it can be used as a normal pooled
connection.
- [ChDriver.Params](ChDriver.Params.md): Turns an Elixir value into a ClickHouse query parameter: the declared
`{name:Type}` type name, the unquoted/unescaped literal text, and the
wire-level escaping depth that text needs.
- [ChDriver.Protocol](ChDriver.Protocol.md): ClickHouse native-protocol packet types relevant to the initial
connection handshake.
- [ChDriver.Protocol.Block.Compressed](ChDriver.Protocol.Block.Compressed.md): Encodes and decodes ClickHouse native-protocol compressed block envelopes.
- [ChDriver.Protocol.Block.Sparse](ChDriver.Protocol.Block.Sparse.md): ## Sparse serialization
- [ChDriver.Protocol.Block.Wrappers](ChDriver.Protocol.Block.Wrappers.md): Decoders for ClickHouse's wrapper/compound column types, dispatched from
`ChDriver.Protocol.NativeBlock`'s `decode_column_data/3`: `Nullable(T)`,
`Array(T)`, `Map(K, V)`, `LowCardinality(T)`, and `Decimal(P, S)`.
`Nullable`/`Array`/`Map`/`LowCardinality` each recurse back into
`ChDriver.Protocol.NativeBlock`'s `decode_column_data/3` for their inner
type(s) -- this mutual recursion across the module boundary is what
makes arbitrarily nested types like `Array(Nullable(String))` or
`Map(String, Array(UInt32))` work for free; see
`ChDriver.Protocol.NativeBlock`'s moduledoc for how new wrapper types
should be added alongside these.
- [ChDriver.Protocol.ClientHello](ChDriver.Protocol.ClientHello.md): The initial packet sent by the client to open a connection.
- [ChDriver.Protocol.Messages](ChDriver.Protocol.Messages.md): Per-message byte layouts for the ClickHouse native protocol.
- [ChDriver.Protocol.NativeBlock](ChDriver.Protocol.NativeBlock.md): Decodes ClickHouse's plaintext "Native" block format -- the payload of a
Data (or wire-identical ProfileEvents) packet once any compression
envelope has been stripped away.
- [ChDriver.Protocol.ServerHello](ChDriver.Protocol.ServerHello.md): The server's response to ClientHello, describing itself.
- [ChDriver.Protocol.Varint](ChDriver.Protocol.Varint.md): LEB128-style unsigned varint encoding used throughout ClickHouse's native
protocol for packet-type discriminants, lengths, revisions, and other
small-to-medium unsigned integers.
- [ChDriver.Query](ChDriver.Query.md): A query for `ChDriver.DBConnection` -- a raw SQL string, optionally
containing `?` positional placeholders (rewritten by `parse/2` into
ClickHouse native `{name:Type}` parameter placeholders at execute time)
or literal `{name:Type}` placeholders written directly by the caller.
- [ChDriver.Result](ChDriver.Result.md): The result of executing a `ChDriver.Query`, returned from
`DBConnection.execute/3,4` via `ChDriver.query/2,3`.

- [ChDriver.Stream](ChDriver.Stream.md): An `Enumerable` that lazily executes a query and yields its rows one
ClickHouse wire-protocol Data block at a time, instead of buffering the
whole result in memory the way `ChDriver.query/2,3,4` does.
- [ChDriver.Types](ChDriver.Types.md): Parses ClickHouse's column *type strings* (e.g. `"Nullable(String)"`,
`"Map(String, Decimal(10, 2))"`) into their component parts. Pure string
parsing only -- no wire decoding happens here; see
`ChDriver.Types.Registry` for the scalar codec table and
`ChDriver.Protocol.Block.Wrappers` / `ChDriver.Protocol.Block.Sparse` for
how these parsed types drive decoding of wrapper/compound column data.
- [ChDriver.Types.Registry](ChDriver.Types.Registry.md): The scalar/fixed-width type codec table (`column_codec/1`) plus the
primitive wire readers it hands out: `decode_fixed_width/4` (fixed-width
binary chunks, one per row, each run through a per-type unpack function)
and `decode_strings/3` (ClickHouse's length-prefixed `String` encoding).

- Exceptions
  - [ChDriver.Error](ChDriver.Error.md): Represents a `DB::Exception` (or `DB::NetException`) returned by the
server in an Exception packet (Server packet type 2).

