The local guide

Start with
one commit.

The preview runs from an extracted archive. No Rust, Node, Docker or cloud account is needed.

Create, write, reopen.

./bin/polybase init ./my-db
./bin/polybase batch ./my-db put projects/one active put projects/two planned
./bin/polybase get ./my-db projects/one
./bin/polybase events ./my-db 0 10
./bin/polybase snapshot ./my-db
./bin/polybase-console ./my-db

Each CLI invocation opens and closes the directory. A successful batch publishes all mutations together. The local console owns the directory until you stop it. Do not delete a live LOCK file to open a second owner.

Browse records, edit UTF-8 or hex bytes, stage several changes and explicitly commit. Expected values reject stale edits. Keys such as projects/one are ordinary bytes; they do not create a document schema. Add a second console argument to choose another port.

Snapshots, queries and retention.

A local snapshot at position S covers the committed prefix through S. Later events follow strictly after S. Native queries combine a byte-key range with a whole-value any, equals or prefix predicate. They do not inspect document fields or run SQL.

Save the applied query result with its last cursor. Resume can repeat delivery. A checkpoint preserves retained history; compaction explicitly advances its floor and can expire old cursors or requests. The console’s default compaction protects live subscribers. Storage limits reject writes instead of silently pruning history.

Keep the original request.

If a console write loses its response, the tab keeps its token and exact intent in session storage. Inspect the durable outcome before deciding what to do. An explicit retry uses that same token and intent; a retained identical request returns its original outcome without another mutation event.

Absence is an observation, not cancellation. An expired or mismatched token needs application reconciliation. Raw CLI writes do not have a named request identity. After a storage failure, close and reopen before inspecting recovered state. Never automatically retry an uncertain write with a new ID.

Explore the three-node research lab.

python3 scripts/start-local-cluster.py ./my-lab --bin-dir ./bin

Python 3.10+ is needed for this optional launcher. Open http://127.0.0.1:7342. It starts three detached loopback nodes on ports 7351–7353 with separate data. Select the observed leader for writes and quorum-confirmed reads. Local follower reads can be stale; a majority acknowledgment does not mean every follower has applied the write.

Closing the cluster console leaves database nodes running. Logs and observed PID files are in the lab directory. Stop only your own processes after checking their commands; an old PID file alone cannot identify a live process. Rerunning preserves the existing binding. Missing bound storage requires investigation, never an automatic voter reset.

This lab has exactly three voters and one partition. There is no public-network authentication, TLS, membership change, sharding or cross-partition transaction support. Keep it on loopback. See the bundled REPLICATION.md for manual startup and the protocol contract.

Back up the complete closed directory.

Stop every owner, then copy the entire database directory, including identity, manifest and generation files. The outer replica binding and its whole inner store form one unit. There is no online backup or repair command. Do not run writable copies of one identity or restore a stale voting directory into a live partition.

Exact guarantees, bounded scope.

Successful local commits follow WAL synchronization, frontier synchronization, atomic rename, directory synchronization and publication. Detected protected corruption fails closed. A failure after a write begins can leave its outcome uncertain.

The default local engine bounds transaction payloads to 1 MiB, state payloads to 64 MiB and retained WAL to 256 MiB. The replicated lab has tighter bounds. These are logical data limits, not hard process-memory or latency guarantees.

Filesystem and hardware synchronization semantics are assumed. Process crash tests do not prove sudden power-loss survival. The preview provides no encryption, general query planner, production support, SLA or exactly-once external side effects. Read the bundled GUARANTEES.md for the full contracts.

Get the evaluation preview ↓