# Polybase local client
Bounded synchronous HTTP client for a local Polybase console. This crate contains
the standalone client and depends on `serde` and `serde_json`. It does not contain
the private database engine or a hosted service. Requires Rust 1.89 or newer and
a separately installed Polybase console; version 0.8.2 is the release
qualification target.
```sh
cargo add polybase-client@0.8.2
```
Start `polybase-console /path/to/database 7340`, then:
```rust
use polybase_client::{Client, Query};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new("127.0.0.1:7340".parse()?)?;
let read = client.read_revision(b"tasks/1")?;
let receipt = client.write_revision(
&read.revision, Some(br#"{"status":"open"}"#),
)?;
let page = client.page(&Query::all(b"tasks/"), None, 64)?;
println!("{} {}", receipt.position, page.rows.len());
Ok(())
}
```
`read_revision` returns an opaque revision for a conditional `write_revision`.
`Error::Api { status: 409, .. }` reports a stale revision. A transport timeout can
leave a write's outcome uncertain: the server can still commit. The client never
automatically retries writes. Reconcile application state before another write.
Query pages have a captured position and an optional continuation cursor. Keep
the query and pass `page.next.as_deref()` to subsequent `page` calls until it is
`None`. Keys and values in returned rows are lowercase hexadecimal bytes; use
`unhex` to decode them. Positions are decimal strings.
`subscribe` captures initial rows and a token. Persist those together. `poll`
takes the application's last applied token explicitly: apply complete commit
transitions and atomically persist rows and the returned token before advancing.
On restart call `resume` with the saved token. Delivery can repeat, tokens can
expire, and the client does not silently take a new snapshot. `Client::call`
provides serde-typed access to other documented routes.
The client supports IPv4 loopback only, uses blocking standard-library TCP,
bounds requests to 128 KiB and responses to 8 MiB, and sets five-second connect,
read and write socket timeouts. A read timeout is a per-socket-operation timeout,
not a deadline for the entire response. Keep the console on loopback.
See the [Polybase documentation](https://base.polymathlabs.xyz/docs) for server
installation, limits and protocol guarantees. Client terms are in `LICENSE`.