#moonchdb

moon add moonbitstack/moonchdb

#Quickstart

async fn run() -> Unit raise {
  let db = @moonchdb.ClickHouseConn::connect(
    "127.0.0.1", user="default", database="default",
  )
  db.execute(
    "CREATE TABLE hero (id Int32, name String) ENGINE = Memory", [],
  )
  |> ignore

  // `?` becomes ClickHouse's own `{p1:Type}` parameter, chosen from the bound value,
  // and the value travels beside the query — never spliced into the SQL.
  db.execute("INSERT INTO hero VALUES (?, ?)", [
    @moondb.Int(1), @moondb.Text("Nova"),
  ])
  |> ignore

  let rows = db.query("SELECT name FROM hero WHERE id = ?", [@moondb.Int(1)])
  println(rows[0].text_by("name")) // Nova

  db.close()
}

#What it speaks

POST /?database=…&default_format=RowBinaryWithNamesAndTypes&param_p1=…
X-ClickHouse-User: …
X-ClickHouse-Key: …

SELECT name FROM hero WHERE id = {p1:Int32}

#Type mapping

#What an analytical engine does not have

• No transactions. begin, commit and rollback are accepted and do nothing; capabilities().transactions is false, and the conformance matrix records the two transaction cases as skipped for this engine.
• No savepoints, and therefore no nested transactions.
• No server-side cursor. query_stream materialises, because the HTTP interface answers one request with one result.
• No prepared statements. prepare returns the buffered handle: the SQL text is re-sent with new parameters, which is what the interface does anyway.
• No unique constraints. A second insert of the same key is accepted; use ReplacingMergeTree and FINAL when that matters, or check first.
• No RETURNING.
• Bool is UInt8 on the wire, and flag = true reads back as Bool because the driver maps the type string, not the value.
• A String column is a byte string. The driver returns Text when the bytes are valid UTF-8 and Blob when they are not, so nothing is silently replaced.
• DateTime carries no zone. The HTTP interface returns epoch seconds and the driver renders them in UTC; DateTime64 keeps its declared scale as fractional seconds.

#Tested against a real ClickHouse

#Not covered

• The native TCP protocol. It would buy a persistent connection and columnar compression; the HTTP interface is what the driver implements, and the contract does not need either.
• Compression (gzip, zstd) on the HTTP body.
• TLS. The interface is plain HTTP here; front it with a proxy that terminates TLS, or open the socket through @moontls in a fork, and the request bytes do not change.
• INSERT … FORMAT bulk loading. A large load belongs in clickhouse-client or a file upload, not in a row-at-a-time driver.

#License