mirror of
https://github.com/hanzo-ds/rs.git
synced 2026-10-30 20:49:56 +00:00
zeekay
86788566d1
Cut from the upstream v0.13.3 release tag (not HEAD) so this is a pure
rename with no behaviour change. v0.13.3 is what our consumers already
resolve to: insights/rust's Cargo.lock pins clickhouse 0.13.3 and its
manifest already declares `datastore` at 0.13.x.
The load-bearing change is the HTTP auth header rename. The Datastore
server reads only X-Datastore-User / X-Datastore-Key; the upstream names
return `401 Code: 194 Authentication failed`. Every un-renamed HTTP
client is therefore unable to authenticate at all — this is a
correctness fix, not branding.
- crate `clickhouse` -> `datastore`, `clickhouse-derive` -> `datastore-derive`;
versions preserved exactly (0.13.3 / 0.2.0).
- derive macro emits `datastore::Row` in lockstep, so downstream
`#[derive(Row)]` keeps resolving.
- User-Agent reports `datastore-rs/{version}`.
- test-harness env vars CLICKHOUSE_* -> DATASTORE_*; compose uses
ghcr.io/hanzoai/datastore with /etc/datastore-server config paths.
- doc links point at docs.hanzo.ai/datastore.
- `publish = false`: the `datastore` name on crates.io belongs to an
unrelated crate, so consume this by git tag, never by version range.
CHANGELOG is truncated to a fork notice rather than find-replaced —
rewriting upstream release history would manufacture changes Datastore
never shipped. References to upstream issues keep their numbers.
3.5 KiB
3.5 KiB
Datastore Rust client examples
Overview
We aim to cover various scenarios of client usage with these examples. You should be able to run any of these examples, see How to run section below.
If something is missing, or you found a mistake in one of these examples, please open an issue or a pull request.
General usage
- usage.rs - creating tables, executing other DDLs, inserting the data, and selecting it back. Additionally, it covers
WATCHqueries. Optional cargo features:inserter,watch. - mock.rs - writing tests with
mockfeature. Cargo features: requirestest-util. - inserter.rs - using the client-side batching via the
inserterfeature. Cargo features: requiresinserter. - async_insert.rs - using the server-side batching via the asynchronous inserts Datastore feature
- datastore_cloud.rs - using the client with Hanzo Datastore Cloud, highlighting a few relevant settings (
wait_end_of_query,select_sequential_consistency). Cargo features: requiresrustls-tls; the code also works withnative-tls. - datastore_settings.rs - applying various Datastore settings on the query level
Data types
- data_types_derive_simple.rs - deriving simpler Datastore data types in a struct. Required cargo features:
time,uuid. - data_types_derive_containers.rs - deriving container-like (Array, Tuple, Map, Nested, Geo) Datastore data types in a struct.
- data_types_variant.rs - working with the Variant data type.
- data_types_new_json.rs - working with the new JSON data type as a String.
Special cases
- custom_http_client.rs - using a custom Hyper client, tweaking its connection pool settings
- custom_http_headers.rs - setting additional HTTP headers to the client, or overriding the generated ones
- query_id.rs - setting a specific
query_idon the query level - session_id.rs - using the client in the session context with temporary tables
- stream_into_file.rs - streaming the query result as raw bytes into a file in an arbitrary format. Required cargo features:
futures03. - stream_arbitrary_format_rows.rs - streaming the query result in an arbitrary format, row by row. Required cargo features:
futures03.
How to run
Prerequisites
- An up-to-date Rust installation
- Datastore server (see below)
Running the examples
The examples will require a running Datastore server on your machine.
You could install it directly, or run it via Docker:
docker run -d -p 8123:8123 -p 9000:9000 --name chrs-datastore-server --ulimit nofile=262144:262144 ghcr.io/hanzoai/datastore
Then, you should be able to run a particular example via the command-line with:
cargo run --package datastore --example async_insert
If a particular example requires a cargo feature, you could run it as follows:
cargo run --package datastore --example usage --features inserter watch
Additionally, the individual examples should be runnable via the IDE such as CLion or RustRover.