Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

This manual documents patinaDB 0.22.0.

Revision 0.22.0

Hardens backup/recovery, ordered mutation execution, query resource limits and transaction lifetimes. Adds mixed-direction partial-prefix ordering and release SBOM/notice verification. See 0.22.0 Release Notes for compatibility boundaries and the pending candidate qualification. Historical soak results do not qualify this new candidate; publication is still separate.

Revision 0.21.0

Improves eligible cold filtered traversals and aggregates, preserves procedure bindings after WITH and in correlated subqueries, and adds independently checked WASM workload coverage. See 0.21.0 Release Notes for the separate six-hour non-WASM and thirty-minute WASM qualification results. Release preparation does not imply that tagged artifacts are already published.

Revision 0.20.0

Adds stable multi-key ordered-edge pagination with residual filters and ordinary graph continuation. This revision also includes the maintenance jobs, recovery, diagnostic tracing and cache improvements merged since 0.17.0. See 0.20.0 Release Notes for the three-hour mixed qualification, upgrade boundaries and remaining cold-aggregation and author-page latency gaps. The version number is not a claim of universal production readiness.

Revision 0.17.0

Fulltext index construction groups postings through a bounded external-sort buffer instead of repeatedly rewriting each term list for every document. Storage format and synchronous incremental maintenance remain unchanged. See 0.17.0 Release Notes for measurements and boundaries.

Revision 0.16.0

Adds bounded parallel vector-index training, cached initialization distances, and incremental candidate consumption during vector search. See 0.16.0 Release Notes for scope and validation.

Revision 0.15.1

Portable restore parses its bounded upload incrementally instead of buffering the full JSON document first. Administrators can explicitly configure a larger restore byte cap; decoded graph/history objects still require RAM. See Backup & Disaster Recovery. The revision also fixes the backup qualification harness; no production approval follows from the bump.

Revision 0.15.0

This revision adds region-aware Bolt routing and scoped causal bookmarks, includes the post-0.13.0 correctness/security fixes, and provides automated release qualification. Read the 0.15.0 release notes for upgrade boundaries and the still-open concurrent-onboarding latency gate. Publication of this manual is not production approval or a binary release.

Revision 0.13.0

This revision preserves valid property-population metadata when existing property values are overwritten, including replicated bulk writes. It is a generic storage correction, not a Jira-specific query rewrite (#1261). It also adds actual snapshot/purge indices to the operator metrics and reproducible logged-fixture worker restart tests. See First Customer for measured local recovery coverage and the required backend retry behavior. A version bump is not WAN qualification or production release approval; see Limitations.

patinaDB is a managed graph database server, deployed as a Docker container. It stores a property graph — vertices (nodes) and directed edges (relationships), each carrying typed properties — on top of an embedded, single-file ACID B-tree storage engine with native cross-tree atomic commits. You query it with a Cypher-like language over your choice of two wire protocols, and every write is recorded as an engram so you can inspect history and travel back in time.

patinaDB (patinadb-raft) is a standalone node that replicates writes with the Raft consensus protocol, hosts multiple databases, and speaks both a JSON REST API and the native Bolt protocol used by Neo4j drivers and the Neo4j Browser. A single node with --bootstrap is a drop-in lightweight server (a “cluster” of one, no consensus-latency penalty for a single voter); add peers to get automatic failover.

What makes patinaDB distinct

  • Versioned by construction. Every mutation is committed as an engram — a git-like commit for your graph. List the history, view a git-style diff of any single change, diff two arbitrary points in time, tag a meaningful state, and run read queries against the past with USE … AS OF. No audit table to bolt on — the history is the database.
  • Provenance, for free. Because the history is a first-class change stream, patinaDB’s Anamnesis system auto-projects it into a queryable PROV graph in a companion database — who / what / when, and optional source / confidence / derived_from at commit, type, attribute, or per-entity granularity, enriched straight from Neo4j transaction metadata. Where Neo4j leaves you to assemble this from APOC triggers or CDC, here it ships in the engine. See Anamnesis.
  • Cypher-compatible. The engine passes ~97% of the openCypher Technology Compatibility Kit (TCK). See Cypher Support for exactly what is and isn’t covered.
  • Neo4j-tooling-compatible. The server’s Bolt endpoint works with the official Neo4j drivers and the Neo4j Browser, so you can point existing tools straight at patinaDB.
  • Search is built in. Full-text search with BM25 ranking and vector/embedding search (an IVF ANN index, cosine & euclidean) ship in the engine — with the same procedure syntax as Neo4j (db.index.fulltext.queryNodes, db.index.vector.queryNodes). No external search service, no separate vector database.
  • Scales down and up. A one-node cluster (quorum of 1) behaves like a plain lightweight server with no consensus latency; add peers for automatic failover (High Availability). Snapshots and time-travel reconstruction stream in O(chunk) memory, so the graph isn’t bounded by RAM.

Who this manual is for

This is the user manual — how to install, query, operate, and integrate patinaDB. It documents every user-facing feature and, just as importantly, its limitations.

A note on scope

patinaDB deliberately implements a subset of Neo4j/Cypher. It is not a drop-in Neo4j replacement for every workload — it targets versioned/auditable graphs and small-to-medium replicated deployments. Where behaviour differs from Neo4j, this manual calls it out explicitly. Read the Limitations chapter before committing to a production workload.