rhiza

package module
v0.12.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2026 License: MIT Imports: 27 Imported by: 0

README

Rhiza

Rhiza is an embedded-first, leaderless Go database with SQL, Graph, KV, and notification APIs. Any healthy voter can accept a write. QuePaxa records a certified decision on a quorum before Rhiza acknowledges it, while local reads remain available without a quorum. The HTTP server is an optional adapter over the same Go API.

Highlights

  • One cgo-free runtime for SQLite, Graph, KV, and notifications.
  • Fixed-membership, leaderless replication over QUIC.
  • Local and linearizable read consistency.
  • Idempotent mutations with bounded receipts and request-status lookup.
  • Certified object-store archives and checkpoints.
  • Non-voting object-store replicas and low-lag learners.
  • Embedded Go API first; HTTP and the rhiza server binary are optional.

Requirements and installation

Rhiza requires Go 1.27 or newer. GOTOOLCHAIN=auto is expected. SQLite uses ncruces/go-sqlite3, and Graph uses latticedb-go, both without cgo.

go get github.com/mrchypark/rhiza

Quick start

Open starts the embedded engine and its private peer endpoint. It does not open a public HTTP listener.

db, err := rhiza.Open(ctx, rhiza.Config{
    NodeID:  "node-1",
    DataDir: "./rhiza-data",
})
if err != nil {
    return err
}
defer db.Close()

_, err = db.Execute(ctx, rhiza.ExecuteRequest{
    RequestID: "schema-1",
    SQL:       "CREATE TABLE tea (id INTEGER PRIMARY KEY, name TEXT)",
})
if err != nil {
    return err
}

rows, err := db.Query(ctx, rhiza.QueryRequest{
    SQL:         "SELECT id, name FROM tea",
    Consistency: rhiza.ConsistencyLocal,
})
if err != nil {
    return err
}

SQL, Graph, KV, notification, stream, and request-status methods are available directly on DB. Use db.Handler() or db itself as an http.Handler when the HTTP adapter is needed.

Embedded Rust SDK

The Rust SDK links Rhiza into your process through a C FFI; it uses the embedded Go API without a public HTTP server. From this checkout:

cargo run --manifest-path sdk/rust/Cargo.toml --example embedded

Use rhizadb = "0.12.0" in your Cargo dependencies. Native builds support macOS and Linux GNU and require Rust, Go 1.27+, and a C compiler. The Rust bridge requires cgo; Go-only applications remain cgo-free. Calls are synchronous, and the embedded engine still starts its private peer endpoint. SQL, KV, Graph, stream, and request-status access are documented in the SDK README.

Consistency and failure model

Local reads use the node's applied state. Linearizable reads first decide a unique read barrier and return ErrQuorumUnavailable when a quorum cannot be reached; they never fall back to stale data.

With three voters, one failed voter preserves writes and linearizable reads. Two failed voters preserve local reads only. DB.Ready() means local recovery and startup catch-up completed; it is not a live quorum probe. Use an inexpensive linearizable query when current quorum readiness matters.

All mutations require a unique request_id. During the idempotency window, retrying the same request with the same payload returns its retained result; reusing the ID with different intent returns ErrRequestConflict. ErrCommitUnknown means the caller must inspect the request status rather than submit a different operation under the same ID. Use the RequestKind*, RequestState*, and MutationCommitted/ MutationRejected constants instead of comparing wire strings directly.

Data APIs

SQL

Rhiza exposes SQLite's DDL, views, triggers, generated and STRICT tables, partial and expression indexes, CTEs and recursive CTEs, joins, subqueries, UPSERT, RETURNING, window functions, JSON functions, and FTS5.

Replicated execution rejects explicit transaction control, attachment, and known nondeterministic functions. Use Execute for one mutation, ExecuteReturning for bounded mutation rows, ExecuteReturningOne when the mutation must produce exactly one row, or a prepared Statements array for an atomic multi-statement transaction. Generic ExecuteReturningMap helpers map rows through a typed Go callback; SQLRow exposes read-only Len, Columns, Values, Value, and Named accessors. SQL values are nil, int64, float64, string, or []byte, and replicated BLOB arguments retain their Go type. A later statement can bind a value from the exactly one row of an earlier WantRows statement through OutputRefs, by a unique column name or index. Reference targets use plain ? parameters and must have a matching null entry in Args. Returned rows and idempotency receipts are retained together, so retrying the same request ID returns the original result without re-executing the mutation.

Each statement can require an exact result with ExpectedRowsAffected for a non-row-returning statement or ExpectedReturnedRows for a WantRows statement. A mismatch rolls back the whole transaction and returns a rejected receipt with MutationErrorCodePreconditionFailed. Use these checks with version predicates and database constraints to keep validation and mutation in the same replicated transaction.

DB.Migrate applies named, contiguous migration versions starting at 1 through the same replicated transaction path. Reapplying an identical migration list is a no-op; changing an already-applied version or leaving a gap is an error. Migration statements are SQL-only (no arguments, returned rows, or output references). The private _rhiza_migrations ledger and each migration are committed atomically, and the reserved _rhiza_ namespace is inaccessible through public SQL APIs.

Graph and Cypher

Rhiza uses latticedb-go v0.3.0 and exposes its deliberately small, case-sensitive Cypher subset. This is not full openCypher. Structural keywords must be uppercase.

Supported query building blocks include:

  • MATCH with fixed-length incoming, outgoing, or undirected patterns.
  • WHERE with comparisons, IN, STARTS WITH, ENDS WITH, CONTAINS, IS NULL, IS NOT NULL, AND, OR, and NOT.
  • RETURN, DISTINCT, count, ORDER BY, SKIP, and LIMIT.
  • Standalone CREATE of one node.
  • MATCH ... SET, MATCH ... CREATE for relationships, REMOVE, DELETE, and DETACH DELETE.
  • UNWIND ... RETURN, UNWIND ... CREATE, and UNWIND ... MATCH.
  • Full-text @@ predicates, subject to the engine's ranking restrictions.

OPTIONAL MATCH, MERGE, WITH, UNION, variable-length paths, list literals, and backtick identifiers are not supported. A standalone relationship creation such as CREATE (:Person)-[:KNOWS]->(:Person) is also unsupported; create or match the nodes first, then use MATCH ... CREATE. Named parameters accept JSON-compatible null, boolean, string, number, list, and map values.

The dependency grammar also includes vector-distance <=>, but Rhiza does not currently configure LatticeDB vector mode or expose typed vector parameters, so vector search is not part of Rhiza's supported Graph surface.

Use GraphQuery or POST /graph/query for read-only MATCH ... RETURN and UNWIND ... RETURN queries. Use GraphExecute or POST /graph/execute for replicated mutations. Mutation statements are applied atomically with their request receipt and optional stream events.

The embedded GraphReachable API performs a bounded outgoing traversal on one immutable local graph snapshot. Callers must provide depth, result, scanned-edge, and encoded-byte limits. It reports StartFound, AppliedSlot, and ConsensusTip, supports an optional RequireAppliedSlot precondition, and orders results by distance then internal node ID. A limit failure returns ErrGraphResourceLimit without partial nodes.

The exported MaxGraphReachable* constants expose the library ceilings.

Declare lookup indexes with Config.LocalGraphNodePropertyIndexes. These indexes are node-local derived state: they are not replicated, and Rhiza reconciles them when the node opens or installs a checkpoint.

The dependency owns the complete language contract. See the version-pinned Supported Cypher Subset and canonical EBNF grammar.

Graph streams

GraphChanges reads the node-local semantic changefeed. Named graph streams can be published atomically with a graph mutation, read by sequence, trimmed, and tracked with replicated durable consumer offsets.

KV and notifications

The KV API supports get, put, delete, compare-and-swap, and TTL. Notification publication is replicated; subscriptions are bounded, live, at-most-once streams. Slow subscribers may drop notifications, so use graph streams when a durable cursor is required.

Limits

  • HTTP JSON bodies: 1 MiB.
  • Canonically encoded consensus mutations: 128 KiB.
  • SQL or Cypher text: 256 KiB.
  • SQL/Cypher arguments: 999.
  • Statements in one SQL transaction: 64.
  • SQL query or RETURNING result rows: 10,000.
  • SQL query result size: 16 MiB total; replicated RETURNING result size: 1 MiB total. Each cell is limited to 1 MiB.
  • Request IDs: 64 bytes.

An HTTP request below 1 MiB may still exceed the encoded consensus limit. Embedded SQL callers can preflight the exact mutation with rhiza.ValidateExecuteRequest and inspect rhiza.MaxReplicatedMutationBytes.

HTTP adapter

The optional adapter exposes:

  • SQL: POST /sql/execute, /sql/execute-returning, /sql/execute-returning-one, /sql/transaction, /sql/query.
  • Graph: POST /graph/execute, /graph/query, /graph/changes.
  • Graph streams: POST /graph/streams/read, POST /graph/streams/offset, PUT /graph/streams/offset, and POST /graph/streams/trim.
  • KV: POST /kv/put, /kv/get, /kv/delete, /kv/cas.
  • Notifications: POST /notify/publish, GET /notify/subscribe.
  • Operations: POST /request/status, GET /metrics/object-store, GET /replica/status.
  • Health: GET /ready, GET /healthz.
curl --fail-with-body http://127.0.0.1:8080/sql/query \
  -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT 1","consistency":"local"}'

Errors use one JSON envelope: {"code":"invalid_request","error":"..."}. Stable codes include invalid_request, request_conflict, not_ready, overloaded, durability_unavailable, commit_unknown, and quorum_unavailable. A commit_unknown response also carries request_id, slot, and retry_through_slot. Unsupported methods return an Allow header. Go clients can decode rhiza.HTTPErrorResponse and compare its code with the rhiza.HTTPErrorCode* constants. SQL BLOB parameters use {"$rhiza_blob":"<base64>"} in HTTP JSON; returned BLOB values are base64 JSON strings.

Query endpoints accept local or linearizable consistency. Read replicas serve the read routes but return HTTP 503 for mutations. The HTTP adapter has no built-in client authentication and must not be exposed directly to an untrusted network.

SQL, KV, and Graph reads share a per-instance admission limit: 64 concurrent reads, including at most 8 waiting graph-stream reads. Saturation returns ErrOverloaded (HTTP 503). Config and ReplicaConfig accept MaxConcurrentReads and MaxLongPollReads; both zero use the defaults, while an explicit total with zero long polls disables waiting stream reads. The CLI exposes RHIZA_MAX_CONCURRENT_READS and RHIZA_MAX_LONG_POLL_READS. HTTP reads retain their slot until the response write completes; embedded calls release it on return. This bounds active reads, not total process memory or results retained by callers. Request-status checks and SSE use their existing paths separately.

Non-voting read replicas

Read replicas serve the SQL, Graph, KV, graph-stream, request-status, and HTTP read APIs, but never propose, vote, acknowledge decisions, or participate in quorum and read-index calculations. Linearizable reads return ErrQuorumUnavailable; use Status().LagSlots to observe bounded staleness. The HTTP status response also includes lag_slots.

Mode Source Tradeoff
object-store Certified checkpoints and archives Best for broad fan-out; adds object-store polling latency and requests.
learner Voter decision streams, then object storage Lower lag; adds one read stream per polling learner. 
replica, err := rhiza.OpenReadReplica(ctx, rhiza.ReplicaConfig{
    ClusterID:        "prod",
    ReplicaID:        "read-1",
    DataDir:          "./read-1",
    Members:          []rhiza.ReplicaMember{{ID: "n1"}},
    ObjStoreProvider: rhiza.ObjectStoreProviderS3,
    ObjStoreBucket:   "rhiza",
})

Both modes require shared object storage for cold start and recovery. Learners authenticate the read-only Sync RPC with the voter AdminToken, but must not receive voter tokens. Build token-free pinned peer identities with rhiza.NewReplicaMember(clusterID, voter).

GET /replica/status reports the mode, applied slot, observed source tip, lag, source, last sync time, and last error. Replica Ready means local recovery completed, not that the copy is current.

After a successful certified recovery, an unchanged archive head with no local apply gap requires only one metadata check per sync. New heads and restarts still use recovery pins and certificate validation. A running replica reuses its pin owner across successful recovery passes, so idle polling does not create a new pin object each time.

/metrics/object-store exposes logical bucket calls separately from actual http_requests, http_failures, and HTTP method counters. Legacy s3_http_* fields remain aliases. HTTP counts include SDK attempts, not a provider billing estimate; sdk_retries currently recognizes the AWS retry header only.

Storage, durability, and recovery

The certified QLog is the source of truth. SQLite and LatticeDB are rebuildable materialized state. Startup replays missing decisions; unreadable local state is quarantined and rebuilt. Checkpoints capture both engines at the same applied slot and restore them together.

Single-voter deployments may use local filesystem storage. Multi-voter clusters require shared S3-compatible, GCS, or Azure Blob storage. Read replicas must reach the same published namespace; their filesystem provider is useful only when that directory is shared or mounted. Object-store durability modes are:

  • async: acknowledge after quorum certification and publish in the background.
  • before-ack: wait for durable object-store publication before acknowledging.

S3 supports custom endpoints and insecure HTTP for local-compatible stores. GCS uses service-account JSON. Azure supports its standard credentials and custom endpoint, but GCS endpoint overrides and insecure GCS/Azure transports are rejected rather than ignored.

Server binary and deployment

go run ./cmd/rhiza starts the optional HTTP server. RHIZA_ROLE selects the runtime:

  • voter (default): voting read/write node.
  • object-store: non-voting object-store replica.
  • learner: non-voting peer-first learner.

Common settings are:

Variable Default Purpose
RHIZA_ROLE voter voter, object-store, or learner
RHIZA_CLUSTER_ID cluster-a Stable cluster identity
RHIZA_NODE_ID node-1 Unique voter or replica identity
RHIZA_DATA_DIR ./rhiza-data Durable local state
RHIZA_BIND_ADDR 127.0.0.1:8080 HTTP listen address
RHIZA_PEER_ADDR 127.0.0.1:9090 Voter QUIC listen address
RHIZA_CLUSTER_MEMBERS empty JSON fixed voter membership
RHIZA_REPLICA_MEMBERS empty Learner JSON pinned voter identities
RHIZA_REPLICA_SYNC_INTERVAL 0s Replica polling interval; zero selects the engine default
RHIZA_ADMIN_TOKEN empty Learner-to-voter sync credential
RHIZA_OBJSTORE_PROVIDER empty filesystem, s3, gcs, or azure
RHIZA_OBJSTORE_DIR empty Filesystem provider directory

Cloud credentials and tuning use the remaining RHIZA_OBJSTORE_* variables. RHIZA_FILESYSTEM_DIR remains an alias for RHIZA_OBJSTORE_DIR; conflicting values are rejected. Invalid boolean and duration values fail startup instead of silently changing behavior.

docker build -t rhiza:dev .
docker run --rm --name rhiza -p 8080:8080 \
  -e RHIZA_BIND_ADDR=0.0.0.0:8080 \
  -v rhiza-data:/data \
  rhiza:dev

Kubernetes examples live under deploy/k8s, including three-peer SQL and Graph qualification manifests and both read-replica modes.

Peer security

Peer traffic uses QUIC over UDP with TLS 1.3, pinned identities, bounded frames, and voter-specific membership tokens. The admin token must differ from every voter token. Learners receive only the admin token and token-free pinned voter identities.

This is server authentication and token authorization, not peer mTLS. Keep peer UDP and the unauthenticated HTTP adapter on private networks, restrict them with firewalls or Kubernetes NetworkPolicy, and add authentication or mTLS at the deployment boundary when private-network trust is insufficient.

Development and qualification

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/rhiza

For local Kubernetes qualification, preload rhiza-e2e:dev, apply one of the three-peer manifests under deploy/k8s, and run the matching tests under e2e. Chaos Mesh scenarios live in e2e/chaos.

Benchmark instructions and durable result artifacts live under benchmarks. Performance claims belong with the exact code, environment, and raw measurements that produced them rather than in this README. The last archived LatticeDB v0.2.1 qualification is attached in 2026-09-01-latticedb-0.2.1-current. The same-host reproduction of Hiqlite's official three-node benchmark and its comparison boundaries are in 2026-09-01-hiqlite-local-comparison.

License

MIT

Documentation

Overview

Package rhiza provides the primary in-process Go API. HTTP is an optional adapter.

Index

Constants

View Source 
const (
	ConsistencyLocal                    = "local"
	ConsistencyLinearizable             = "linearizable"
	ObjectStoreDurabilityAsync          = types.ObjectStoreDurabilityAsync
	ObjectStoreDurabilityBeforeAck      = types.ObjectStoreDurabilityBeforeAck
	MutationCommitted                   = types.MutationCommitted
	MutationRejected                    = types.MutationRejected
	MutationErrorCodeExecutionFailed    = types.MutationErrorCodeExecutionFailed
	MutationErrorCodePreconditionFailed = types.MutationErrorCodePreconditionFailed
	RequestKindSQL                      = "sql"
	RequestKindKV                       = "kv"
	RequestKindNotify                   = "notify"
	RequestKindGraph                    = "graph"
	RequestStateCommitted               = "committed"
	RequestStateRejected                = "rejected"
	RequestStateUnknownOrExpired        = "unknown_or_expired"
	ObjectStoreProviderFilesystem       = "filesystem"
	ObjectStoreProviderS3               = "s3"
	ObjectStoreProviderGCS              = "gcs"
	ObjectStoreProviderAzure            = "azure"
	HTTPErrorCodeInvalidRequest         = "invalid_request"
	HTTPErrorCodeRequestConflict        = "request_conflict"
	HTTPErrorCodeNotReady               = "not_ready"
	HTTPErrorCodeOverloaded             = "overloaded"
	HTTPErrorCodeDurabilityUnavailable  = "durability_unavailable"
	HTTPErrorCodeCommitUnknown          = "commit_unknown"
	HTTPErrorCodeQuorumUnavailable      = "quorum_unavailable"
	HTTPErrorCodeMethodNotAllowed       = "method_not_allowed"
	HTTPErrorCodeNotFound               = "not_found"
	// MaxReplicatedMutationBytes is the encoded consensus-value limit.
	MaxReplicatedMutationBytes = quepaxa.MaxReplicatedValueBytes
	// MaxHTTPBodyBytes is the optional HTTP adapter's larger JSON envelope limit.
	MaxHTTPBodyBytes              = network.MaxRequestBodyBytes
	MaxGraphReachableDepth        = materializer.MaxGraphReachableDepth
	MaxGraphReachableResults      = materializer.MaxReturningRows
	MaxGraphReachableScannedEdges = materializer.MaxGraphReachableEdges
	MaxGraphReachableBytes        = materializer.MaxResultBytes
	MaxLocalGraphPropertyIndexes  = materializer.MaxGraphPropertyIndexes
)

Variables

View Source 
var (
	ErrNotReady              = network.ErrNotReady
	ErrRequestConflict       = network.ErrRequestConflict
	ErrInvalidRequest        = network.ErrInvalidRequest
	ErrQuorumUnavailable     = quepaxa.ErrQuorumUnavailable
	ErrDurabilityUnavailable = network.ErrDurabilityUnavailable
	ErrCommitUnknown         = network.ErrCommitUnknown
	ErrGraphResourceLimit    = network.ErrGraphResourceLimit
	ErrReadVersionMismatch   = network.ErrReadVersionMismatch
)

Functions

func ValidateExecuteRequest added in v0.8.1 

func ValidateExecuteRequest(req ExecuteRequest) error

ValidateExecuteRequest applies the replicated SQL contract and encoded-size limit without submitting the mutation.

func ValidateGraphReachableRequest added in v0.10.0 

func ValidateGraphReachableRequest(req GraphReachableRequest) error

ValidateGraphReachableRequest checks limits and value types without reading data.

Types

type Config 

type Config struct {
	ClusterID                      string
	NodeID                         string
	DataDir                        string
	BindAddr                       string
	PeerAddr                       string
	AdminToken                     string
	Members                        []Member
	ObjStoreEndpoint               string
	ObjStoreBucket                 string
	ObjStoreProvider               string
	ObjStoreDir                    string
	ObjStorePrefix                 string
	ObjStoreRegion                 string
	ObjStoreInsecure               bool
	ObjStoreRetries                int
	ObjStoreAccessKey              string
	ObjStoreSecretKey              string
	ObjStoreSessionToken           string
	ObjStoreServiceAccount         string
	ObjStoreAzureTenantID          string
	ObjStoreAzureClientID          string
	ObjStoreAzureClientSecret      string
	ObjStoreAzureStorageAccount    string
	ObjStoreAzureStorageAccountKey string
	ObjStoreAzureConnectionString  string
	ObjStoreAzureUserAssignedID    string
	ObjStoreDurability             ObjectStoreDurability
	ObjStoreSyncInterval           time.Duration
	ObjStoreBatchDelay             time.Duration
	ObjStoreGCInterval             time.Duration
	ObjStoreGCGracePeriod          time.Duration
	CheckpointInterval             time.Duration
	CheckpointTailBytes            int64
	MaxWALBytes                    int64
	// Both zero use 64 concurrent reads / 8 long-poll reads. With an explicit
	// total, zero MaxLongPollReads disables waiting stream reads.
	MaxConcurrentReads int
	MaxLongPollReads   int
	// LocalGraphNodePropertyIndexes are node-local derived indexes. Rhiza
	// reconciles them at open and after checkpoint restore; they are not replicated.
	LocalGraphNodePropertyIndexes []GraphNodePropertyIndex
}

Config contains the durable local path, fixed membership, and peer endpoint.

type DB 

type DB struct {
	// contains filtered or unexported fields
}

DB owns one embedded Rhiza node and its private QUIC peer endpoint.

func Open 

func Open(ctx context.Context, config Config) (*DB, error)

Open starts the embedded engine. It does not start a public HTTP listener.

func (*DB) Close 

func (db *DB) Close() error

func (*DB) Execute 

func (db *DB) Execute(ctx context.Context, req ExecuteRequest) (ExecuteResponse, error)

func (*DB) ExecuteReturning added in v0.9.1 

func (db *DB) ExecuteReturning(ctx context.Context, req ExecuteRequest) (ExecuteResponse, error)

ExecuteReturning executes one replicated mutation and returns its bounded rows.

func (*DB) ExecuteReturningOne added in v0.9.1 

func (db *DB) ExecuteReturningOne(ctx context.Context, req ExecuteRequest) (ExecuteResponse, error)

ExecuteReturningOne commits only when exactly one row is returned.

func (*DB) GraphChanges 

func (db *DB) GraphChanges(ctx context.Context, req GraphStreamReadRequest) (GraphStreamReadResponse, error)

GraphChanges reads the node-local LatticeDB semantic graph changefeed.

func (*DB) GraphExecute 

func (db *DB) GraphExecute(ctx context.Context, req GraphCommand) (GraphExecuteResponse, error)

func (*DB) GraphQuery 

func (db *DB) GraphQuery(ctx context.Context, req GraphQueryRequest) (GraphResult, error)

func (*DB) GraphReachable added in v0.9.0 

func (db *DB) GraphReachable(ctx context.Context, req GraphReachableRequest) (GraphReachableResult, error)

GraphReachable performs a bounded, deterministic outgoing traversal on one immutable local graph snapshot. Results are ordered by distance, then node ID.

func (*DB) GraphStreamOffset 

func (db *DB) GraphStreamOffset(ctx context.Context, req GraphStreamOffsetRequest) (GraphStreamOffsetResponse, error)

GraphStreamOffset returns a replicated durable consumer offset.

func (*DB) GraphStreamRead 

func (db *DB) GraphStreamRead(ctx context.Context, req GraphStreamReadRequest) (GraphStreamReadResponse, error)

GraphStreamRead reads a replicated named stream after its per-stream cursor.

func (*DB) Handler 

func (db *DB) Handler() http.Handler

Handler exposes the optional HTTP server API without opening a listener.

func (*DB) KVCAS 

func (db *DB) KVCAS(ctx context.Context, req KVMutationRequest) (KVMutationResponse, error)

func (*DB) KVDelete 

func (db *DB) KVDelete(ctx context.Context, req KVMutationRequest) (KVMutationResponse, error)

func (*DB) KVGet 

func (db *DB) KVGet(ctx context.Context, req KVGetRequest) (KVGetResponse, error)

func (*DB) KVPut 

func (db *DB) KVPut(ctx context.Context, req KVMutationRequest) (KVMutationResponse, error)

func (*DB) Migrate added in v0.9.1 

func (db *DB) Migrate(ctx context.Context, migrations []Migration) error

Migrate applies strictly ordered migrations exactly once. A repeated version must have the same name and statements.

func (*DB) NotificationDrops 

func (db *DB) NotificationDrops() uint64

func (*DB) NotifyPublish 

func (db *DB) NotifyPublish(ctx context.Context, req NotifyCommand) (MutationReceipt, error)

func (*DB) NotifySubscribe 

func (db *DB) NotifySubscribe(topic string) (<-chan []byte, func(), error)

func (*DB) ObjectStoreStats 

func (db *DB) ObjectStoreStats() (ObjectStoreStats, bool)

func (*DB) Query 

func (db *DB) Query(ctx context.Context, req QueryRequest) (QueryResponse, error)

func (*DB) Ready added in v0.8.1 

func (db *DB) Ready() bool

Ready reports whether local recovery and catch-up completed. It is not a live quorum probe: an isolated peer may remain locally ready. Mutations and linearizable queries still fail closed when quorum is unavailable.

func (*DB) RequestStatus 

func (db *DB) RequestStatus(ctx context.Context, req RequestStatusRequest) (RequestStatusResponse, error)

func (*DB) ServeHTTP 

func (db *DB) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*DB) SetGraphStreamOffset 

func (db *DB) SetGraphStreamOffset(ctx context.Context, req GraphStreamOffsetRequest) error

SetGraphStreamOffset stores a replicated durable consumer offset.

func (*DB) TrimGraphStream 

func (db *DB) TrimGraphStream(ctx context.Context, req GraphStreamTrimRequest) error

TrimGraphStream replicates deletion of records through the supplied sequence.

type ExecuteRequest 

type ExecuteRequest = network.ExecuteRequest

type ExecuteResponse 

type ExecuteResponse = network.ExecuteResponse

func ExecuteReturningMap added in v0.9.1 

func ExecuteReturningMap[T any](ctx context.Context, db *DB, req ExecuteRequest, mapper func(SQLRow) (T, error)) (ExecuteResponse, []T, error)

ExecuteReturningMap maps replicated RETURNING rows to an application type.

func ExecuteReturningMapOne added in v0.9.1 

func ExecuteReturningMapOne[T any](ctx context.Context, db *DB, req ExecuteRequest, mapper func(SQLRow) (T, error)) (ExecuteResponse, T, error)

ExecuteReturningMapOne maps one row and rolls back unless exactly one exists.

type GraphCommand 

type GraphCommand = types.GraphCommand

type GraphExecuteResponse 

type GraphExecuteResponse = network.GraphExecuteResponse

type GraphNodePropertyIndex added in v0.10.0 

type GraphNodePropertyIndex = types.GraphNodePropertyIndex

type GraphQueryRequest 

type GraphQueryRequest = network.GraphQueryRequest

type GraphReachableNode added in v0.10.0 

type GraphReachableNode = types.GraphReachableNode

type GraphReachableRequest added in v0.10.0 

type GraphReachableRequest = types.GraphReachableRequest

type GraphReachableResult added in v0.10.0 

type GraphReachableResult = types.GraphReachableResult

type GraphResult 

type GraphResult = types.GraphCommandResult

type GraphStreamEvent 

type GraphStreamEvent = types.GraphStreamEvent

type GraphStreamOffsetRequest 

type GraphStreamOffsetRequest = network.GraphStreamOffsetRequest

type GraphStreamOffsetResponse 

type GraphStreamOffsetResponse = network.GraphStreamOffsetResponse

type GraphStreamReadRequest 

type GraphStreamReadRequest = network.GraphStreamReadRequest

type GraphStreamReadResponse 

type GraphStreamReadResponse = network.GraphStreamReadResponse

type GraphStreamRecord 

type GraphStreamRecord = types.GraphStreamRecord

type GraphStreamTrimRequest 

type GraphStreamTrimRequest = network.GraphStreamTrimRequest

type HTTPErrorResponse added in v0.9.1 

type HTTPErrorResponse = network.ErrorResponse

type KVGetRequest 

type KVGetRequest = network.KVGetRequest

type KVGetResponse 

type KVGetResponse = network.KVGetResponse

type KVMutationRequest 

type KVMutationRequest = network.KVMutationRequest

type KVMutationResponse 

type KVMutationResponse = network.KVMutationResponse

type Member 

type Member = quepaxa.Member

type Migration added in v0.9.1 

type Migration struct {
	Version    int64          `json:"version"`
	Name       string         `json:"name"`
	Statements []SQLStatement `json:"statements"`
}

Migration is one ordered, repeatable schema change.

type MutationReceipt 

type MutationReceipt = types.MutationReceipt

type MutationStatus added in v0.9.1 

type MutationStatus = types.MutationStatus

type NodeID added in v0.9.1 

type NodeID = quepaxa.NodeID

type NotifyCommand 

type NotifyCommand = types.NotifyCommand

type ObjectStoreDurability 

type ObjectStoreDurability = types.ObjectStoreDurability

type ObjectStoreStats 

type ObjectStoreStats = objstore.Stats

type QueryRequest 

type QueryRequest = network.QueryRequest

type QueryResponse 

type QueryResponse = network.QueryResponse

type ReadReplica added in v0.9.1 

type ReadReplica struct {
	// contains filtered or unexported fields
}

ReadReplica is an eventual, read-only copy. It never proposes, votes, acknowledges decisions, or participates in quorum/read-index operations.

func OpenLearner added in v0.9.1 

func OpenLearner(ctx context.Context, config ReplicaConfig) (*ReadReplica, error)

OpenLearner follows voter peer logs first and falls back to certified object storage after compaction or peer unavailability. It is not cluster membership.

func OpenReadReplica added in v0.9.1 

func OpenReadReplica(ctx context.Context, config ReplicaConfig) (*ReadReplica, error)

OpenReadReplica follows certified checkpoint/archive state only.

func (*ReadReplica) Close added in v0.9.1 

func (r *ReadReplica) Close() error

func (*ReadReplica) GraphChanges added in v0.9.1 

func (r *ReadReplica) GraphChanges(ctx context.Context, req GraphStreamReadRequest) (GraphStreamReadResponse, error)

func (*ReadReplica) GraphQuery added in v0.9.1 

func (r *ReadReplica) GraphQuery(ctx context.Context, req GraphQueryRequest) (GraphResult, error)

func (*ReadReplica) GraphReachable added in v0.11.0 

func (r *ReadReplica) GraphReachable(ctx context.Context, req GraphReachableRequest) (GraphReachableResult, error)

func (*ReadReplica) GraphStreamOffset added in v0.9.1 

func (r *ReadReplica) GraphStreamOffset(ctx context.Context, req GraphStreamOffsetRequest) (GraphStreamOffsetResponse, error)

func (*ReadReplica) GraphStreamRead added in v0.9.1 

func (r *ReadReplica) GraphStreamRead(ctx context.Context, req GraphStreamReadRequest) (GraphStreamReadResponse, error)

func (*ReadReplica) Handler added in v0.9.1 

func (r *ReadReplica) Handler() http.Handler

func (*ReadReplica) KVGet added in v0.9.1 

func (r *ReadReplica) KVGet(ctx context.Context, req KVGetRequest) (KVGetResponse, error)

func (*ReadReplica) ObjectStoreStats added in v0.9.1 

func (r *ReadReplica) ObjectStoreStats() ObjectStoreStats

func (*ReadReplica) Query added in v0.9.1 

func (r *ReadReplica) Query(ctx context.Context, req QueryRequest) (QueryResponse, error)

func (*ReadReplica) Ready added in v0.9.1 

func (r *ReadReplica) Ready() bool

func (*ReadReplica) RequestStatus added in v0.9.1 

func (r *ReadReplica) RequestStatus(ctx context.Context, req RequestStatusRequest) (RequestStatusResponse, error)

func (*ReadReplica) ServeHTTP added in v0.9.1 

func (r *ReadReplica) ServeHTTP(w http.ResponseWriter, req *http.Request)

func (*ReadReplica) Status added in v0.9.1 

func (r *ReadReplica) Status() ReplicaStatus

func (*ReadReplica) Sync added in v0.9.1 

func (r *ReadReplica) Sync(ctx context.Context) error

Sync performs one bounded catch-up pass from the configured source.

type ReplicaConfig added in v0.9.1 

type ReplicaConfig struct {
	ClusterID    string
	ReplicaID    string
	DataDir      string
	AdminToken   string
	Members      []ReplicaMember
	SyncInterval time.Duration
	// Both zero use 64 concurrent reads / 8 long-poll reads. With an explicit
	// total, zero MaxLongPollReads disables waiting stream reads.
	MaxConcurrentReads int
	MaxLongPollReads   int

	ObjStoreEndpoint               string
	ObjStoreBucket                 string
	ObjStoreProvider               string
	ObjStoreDir                    string
	ObjStorePrefix                 string
	ObjStoreRegion                 string
	ObjStoreInsecure               bool
	ObjStoreRetries                int
	ObjStoreAccessKey              string
	ObjStoreSecretKey              string
	ObjStoreSessionToken           string
	ObjStoreServiceAccount         string
	ObjStoreAzureTenantID          string
	ObjStoreAzureClientID          string
	ObjStoreAzureClientSecret      string
	ObjStoreAzureStorageAccount    string
	ObjStoreAzureStorageAccountKey string
	ObjStoreAzureConnectionString  string
	ObjStoreAzureUserAssignedID    string
}

ReplicaConfig configures a non-voting, read-only follower. Members contains only the fixed voters whose certificates the follower verifies.

type ReplicaMember added in v0.9.1 

type ReplicaMember = network.PeerIdentity

func NewReplicaMember added in v0.9.1 

func NewReplicaMember(clusterID string, member Member) (ReplicaMember, error)

NewReplicaMember removes a voter's secret while retaining its pinned peer identity.

type ReplicaMode added in v0.9.1 

type ReplicaMode string
const (
	ReplicaModeObjectStore ReplicaMode = "object-store"
	ReplicaModeLearner     ReplicaMode = "learner"
)

type ReplicaStatus added in v0.9.1 

type ReplicaStatus struct {
	Mode        ReplicaMode
	AppliedSlot uint64
	SourceTip   uint64
	LagSlots    uint64
	Source      string
	LastSync    time.Time
	LastError   string
}

type RequestStatusRequest 

type RequestStatusRequest = network.RequestStatusRequest

type RequestStatusResponse 

type RequestStatusResponse = network.RequestStatusResponse

type SQLRow added in v0.9.1 

type SQLRow struct {
	// contains filtered or unexported fields
}

SQLRow is one immutable row passed to a typed mapping callback.

func (SQLRow) Columns added in v0.9.1 

func (r SQLRow) Columns() []string

Columns returns a copy of the column names in result order.

func (SQLRow) Len added in v0.9.1 

func (r SQLRow) Len() int

Len returns the number of columns in the row.

func (SQLRow) Named added in v0.9.1 

func (r SQLRow) Named(name string) (any, error)

Named returns a uniquely named column.

func (SQLRow) Value added in v0.9.1 

func (r SQLRow) Value(index int) (any, error)

Value returns one column by index.

func (SQLRow) Values added in v0.9.1 

func (r SQLRow) Values() []any

Values returns a copy of the values in result order.

type SQLStatement 

type SQLStatement = types.SQLStatement

type SQLStatementOutputRef added in v0.9.1 

type SQLStatementOutputRef = types.SQLStatementOutputRef

type SQLStatementResult added in v0.9.1 

type SQLStatementResult = types.SQLStatementResult

Source Files

View all Source files

Directories

Path Synopsis
benchmarks
results/2026-09-05-latticedb-0.5.0/compat command
cmd
rhiza command
rhiza-bench command
rhiza-ffi command
internal
objstore
types
pkg
checkpoint
materializer
network
network/peerfb
node
qlog
quepaxa
Package quepaxa implements the crash-fault-tolerant QuePaxa Algorithm 3 recorder and Algorithm 4 proposer over a durable QLog.
 Package quepaxa implements the crash-fault-tolerant QuePaxa Algorithm 3 recorder and Algorithm 4 proposer over a durable QLog.
quepaxa/walfb
recovery

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.