HA deployment status and configuration

ShrikeDB’s cluster mode supports selected replicated data operations and distributed reads. Cluster configuration does not make every query or index available across replicas. Evaluate the exact operations your application needs before choosing this deployment mode.

Available operations

The cluster interfaces include shard placement, write forwarding, synchronous quorum replication for supported KV/graph/vector writes, durable repair metadata and replay data, operation receipts, and transaction commit-decision recovery.

With distributed_query_execution enabled, distributed reads cover bulk KV, packed or streaming vector search, GraphScan, batched neighbor lookup, and graph-scan-shaped Cypher/SPARQL queries. Cypher also supports the bounded global reductions described below. Set proxy_non_replica_reads to true so a coordinator can reach shards it does not hold.

GraphScan returns UID-to-UID edges from property-graph and RDF storage, without duplicating edges present in both representations. It matches bound endpoints and repeated variables before applying a result limit. Send x-shrikedb-database to select a named database; the scan carries that selector to participating nodes. An explicit snapshot version must be available as each queried participant’s published graph version. A matching local version number alone does not establish a cluster-wide transaction snapshot.

The general RDF result model includes literals and other terms beyond this UID scan interface. Qualify the exact SPARQL result shape before using the distributed scan adapter. General joins and paths still require complete distributed inputs. When a query has no distributed implementation and the local node does not hold every shard, the language endpoint returns UNIMPLEMENTED instead of executing against only that node’s data. This check also applies to the HTTP query workspace. A node assigned every shard retains the local query path; placement coverage is separate from replica catch-up and a shared transaction snapshot.

Global edge queries

For fixed, directed relationship patterns, Cypher can combine owner fragments before evaluating joins, row filters, grouping, aggregates, ordering and pagination. These plans use the same query operators as local queries. A single-edge example:

MATCH (sender)-[:SENT]->(recipient)
RETURN sender, count(DISTINCT recipient) AS recipients
ORDER BY recipients DESC
LIMIT 20

Connected patterns can cross shard owners. This query counts the distinct recipients reachable through a relay, excluding the sender:

MATCH (sender)-[:SENT]->(relay)-[:SENT]->(recipient)
WHERE sender <> recipient
RETURN sender, count(DISTINCT recipient) AS recipients
ORDER BY recipients DESC
LIMIT 20

For a query with more than one edge scan, supply snapshot_version in the API request. Each participant must still hold that published version for every scan. A version change causes the request to fail. This participant check does not establish a common transaction snapshot across the cluster.

The admitted shape has one to eight edges, named node bindings and one concrete relationship type per edge. It supports connected mandatory MATCH clauses, WITH, row arithmetic and comparisons, count, sum, avg, min, max, RETURN DISTINCT, ORDER BY, SKIP and LIMIT. A single MATCH cannot reuse the same stored relationship; separate MATCH clauses keep their own relationship uniqueness scope. Node revisits and cycles remain valid.

Start each additional pattern from a node binding already in scope. To follow an incoming edge from that binding, use a left-pointing arrow. Plans whose join key is not available from both inputs do not enter this distributed path.

The coordinator accepts up to 65,536 matching input edges across the scans and checks a conservative bound on join expansion before execution. Both bounds must fit. A selective query can still exceed the conservative bound even when its final answer is small. Such requests return RESOURCE_EXHAUSTED; result limits do not truncate aggregate inputs or turn an incomplete count into a successful answer. Empty ungrouped counts return zero. API pagination applies outside the query’s own pagination, so an API offset cannot escape a query’s LIMIT.

Node labels, property access, relationship bindings, optional patterns, variable-length paths, disconnected cross products and general function calls require other distributed operators or complete local shard coverage. Fully replicated nodes retain their existing local query path without these coordinator input limits. Dedicated Cypher, generic query and HTTP workspace requests use the same routing.

Neighbor and vector reads

BulkNeighbors and BulkNeighborsCompact accept up to 4,096 source nodes. Outgoing lookups target the owners of those sources. Incoming and BOTH lookups gather from the owners of incoming edges as well. The coordinator combines results before applying each node’s result limit and preserves the input node order, including repeated IDs. Compact predicate IDs refer to the dictionary returned in that response. Without predicates, compact BOTH results contain unique neighbor IDs. These adjacency APIs do not enumerate path multiplicities.

Use x-shrikedb-database consistently for neighbor and vector reads. Packed, streaming and batch vector searches carry the selected database to participants. A participant failure fails the distributed neighbor request rather than returning an incomplete list. The participant snapshot limits described above still apply.

Write interfaces

Use semantic-rule creation in standalone deployments. Its current RPC commits locally.

SQL, Cypher and SPARQL language mutations currently require a standalone deployment. In cluster mode, these requests return UNIMPLEMENTED. The supported replicated write APIs listed above are separate from language mutation statements. Enabling the language-write settings does not enable their replication.

Distributed SQL routing also returns UNIMPLEMENTED. Use the supported Cypher/SPARQL read shapes for cluster queries and test the complete query against your deployment configuration.

Geospatial HTTP ingestion enters the normal transaction commit path. The coordinator sends graph, vector, KV, and geospatial writes in one prepare payload, applies them locally after prepare quorum, records the commit decision, and finalizes prepared peers. Cypher and SPARQL geospatial searches run against the replica’s published named-index generation. Use the same database name on every peer; the replicated request carries that database selector during peer apply.

Durability and recovery

Keep transaction identity separate from the storage work that makes it durable. A shared WAL flush can cover several records, but each transaction retains its own decision and recovery receipt. A receipt for durable storage application is one part of the commit path: the server must also satisfy the operation’s replication and modality-publication requirements before acknowledging the client.

The native storage replay path supports bounded groups of admitted independent transactions. It preserves individual records and receipts while sharing WAL synchronization. A partially completed group can leave a durable prefix of transactions for recovery to apply. The group is a storage optimization, not an application transaction that commits or rolls back all members together. Public HA request batching remains a separate integration step; enabling cluster mode does not automatically select this replay optimization for every write.

Recovery advances its checkpoint through a complete durable log prefix. It does not skip an unfinished earlier record because a later write completed. For an active grouped storage commit, cancellation of the waiting request leaves the commit owner responsible for finishing durability and publication. Orderly shutdown waits for that owner before closing the WAL.

For applications, a timeout or lost connection still means an uncertain outcome. Retain the transaction or operation identifier, check the recovered outcome, and use the operation’s supported retry mechanism. Issuing the same business change with a new identity can create a duplicate. After a storage or recovery error, wait for readiness and reconcile the recorded state before resuming writes. Use Transactions, durability, and snapshots for the client workflow.

Plan a cluster evaluation

Use separate persistent data directories and unique node IDs. Each node needs reachable advertised gRPC, HTTP, and admin addresses, a consistent peer list, and compatible replication settings. Protect peer credentials using your deployment’s secret-management mechanism.

Independent-host crash, network-partition, restore, and upgrade qualification remains necessary before relying on this mode for application availability. Include acknowledgment behavior, duplicate retries, repair backlog, and query correctness in that evaluation.

Example overlay

This configuration illustrates a three-node evaluation network. Replace every address and create a corresponding overlay for each node. Save it as ha.yaml and set SHRIKEDB_HA_CONFIG to its absolute path before starting that node.

enabled: true
cluster_name: evaluation
node_id: node-1
advertise_grpc: "10.0.0.11:50251"
advertise_http: "10.0.0.11:8182"
advertise_admin: "10.0.0.11:9190"
replication_factor: 3
shard_count: 256
peers:
  - node_id: node-2
    grpc_addr: "10.0.0.12:50251"
    http_addr: "10.0.0.12:8182"
    admin_addr: "10.0.0.12:9190"
  - node_id: node-3
    grpc_addr: "10.0.0.13:50251"
    http_addr: "10.0.0.13:8182"
    admin_addr: "10.0.0.13:9190"

Set SHRIKEDB_CLUSTER_NODE_TOKEN in each server process’s environment through your secret-management system. A literal ${…} inside YAML is not a substitute for applying the environment override.

The advertised addresses tell peers where to connect. Configure the node’s listener binds separately in its full server configuration. Configuration And Environment lists the cluster environment settings.

Verify behavior

Confirm readiness on each node, then write and read a known test record through the public client interface from different nodes. For a multimodal deployment, commit one graph edge and one geospatial observation in the same transaction, then verify both Cypher and SPARQL reads on each replica. Record returned receipts and expected values before testing a restart or connectivity loss. A timed-out write can have an uncertain outcome; use the operation’s documented retry identity and check recovered state before retrying with a new identity.

Retain the previous standalone deployment or other recovery path until the cluster evaluation satisfies your application’s requirements. Follow the cluster’s recovery procedure for membership and replicated state; a standalone filesystem restore alone is insufficient.