ClickHoused 0.1.2: native ClickHouse client for D (ddbc and HibernateD support coming)

[Vadim Lopatin]

Hi all,

I'd like to announce **ClickHouseD**, a new client library for 
[ClickHouse](https://clickhouse.com), the open-source 
column-oriented database for analytics.

- dub: https://code.dlang.org/packages/clickhoused
- GitHub: https://github.com/buggins/clickhoused
- Docs: https://clickhoused.dpldocs.info/

**Highlights**

- **Pure D, no dependencies.** It implements the ClickHouse 
native TCP protocol (port 9000) directly. It doesn't wrap a C/C++ 
library and doesn't use HTTP. LZ4 compression is written in D 
too; ZSTD is available as an optional dub configuration.
- **Threads and vibe.d fibers.** In ordinary threads it uses 
Phobos sockets. Inside a vibe.d task it switches to vibe-core 
sockets automatically, so a query only suspends its own task. 
vibe-core is an optional dependency (1.22+ and 2.x) and is used 
only when your project already depends on it.
- **Structs or columns.**
   - Map results to D structs with `query!T`, `queryRow!T` and 
`queryValue!T`.
   - Insert any range of structs.
   - Or work block by block with whole columns as typed D arrays.
- **Streaming in both directions.** Large results are read 
lazily, and inserts are sent in blocks as you add rows.
- **Server-side query parameters** (`{name:Type}`), so values 
never end up in the SQL text.
- **Connection pool, failover, cancellation.**
   - DSN connection strings: 
`clickhouse://user:pass@host1:9000,host2:9000/db?compress=lz4`.
   - The connection pool works in both thread and fiber mode.
   - `cancel()` stops a running query from another thread or task.
- **Compatibility:**
   - Tested against ClickHouse 23.8 up to the latest release.
   - D frontend 2.097+ (DMD 2.097+, LDC 1.27+).
   - CI covers Linux, Windows and macOS.
- **License:** Boost (BSL-1.0).

**Quick example**

```d
import clickhoused;

struct Trade
{
     @column("ts") SysTime time;
     string symbol;
     double price;
     uint quantity;
}

auto conn = new 
Connection("clickhouse://default:@localhost:9000/default");
scope (exit) conn.close();

conn.insert("trades", trades);   // any range of structs

foreach (t; conn.query!Trade("SELECT * FROM trades WHERE symbol = 
{sym:String}", null, ["sym": "AAPL"]))
     writeln(t.time, " ", t.price);

const count = conn.queryValue!ulong("SELECT count() FROM trades");
```

**Supported types**

- Integers up to 64 bits, `Float32`/`Float64`, `Bool`
- `String`, `FixedString`
- `Date`, `Date32`, `DateTime`, `DateTime64` (with timezones)
- `UUID`, `Enum8`/`Enum16`, `Nullable(T)`
- `LowCardinality` columns, which are received as their plain type

**Not supported yet:**

- TLS
- `Array`, `Tuple`, `Map`
- `Decimal`, 128/256-bit integers, `IPv4`/`IPv6`
- `Variant`/`Dynamic`/`JSON`

These are planned for the next releases. A query returning an 
unsupported column type fails with a clear error. The API may 
still change before 1.0.

**ddbc and HibernateD**

ClickHouse support is also coming to my database libraries:

- **[ddbc](https://github.com/buggins/ddbc).** A ClickHouse 
driver built on clickhoused is in review: 
https://github.com/buggins/ddbc/pull/137. It's an opt-in 
`ClickHouse` configuration that needs no C libraries. It maps 
prepared statements to typed server-side parameters, streams 
result sets, and locks correctly under both threads and vibe.d 
fibers. URL: `ddbc:clickhouse://host:9000/db?user=default`.
- **[HibernateD](https://github.com/buggins/hibernated).** A 
`ClickHouseDialect` is in a draft PR: 
https://github.com/buggins/hibernated/pull/99. ClickHouse isn't a 
transactional database, so the dialect adapts the ORM to it:
   - tables are created as MergeTree;
   - updates run as synchronous mutations;
   - `@Generated` keys are generated on the client;
   - transactions are reported as unsupported, rather than 
silently not rolling back.

   It needs the next ddbc release.

Feedback, bug reports and feature requests are very welcome, 
especially which missing types you need first. Issues: 
https://github.com/buggins/clickhoused/issues

clickhoused is an unofficial project, not affiliated with 
ClickHouse, Inc. ClickHouse is a trademark of ClickHouse, Inc.

Vadim Lopatin