Documentation
¶
Overview ¶
Package replicated makes orm's per-namespace databases durable.
db.Namespaces resolves a namespace to a handle and bounds how many stay open. It declares three seams and fills in none of them: Materialize on a local miss, OnOpen and OnClose around a handle's life. This package fills them with hanzoai/replicate — while a namespace is held open, that database's SQLite file streams its WAL to object storage; when a node is asked for a namespace it does not have on disk, that file is restored before it is opened. The pair is what lets a node evict a namespace and any node re-materialise it.
One replicator per FILE, never one over the directory. A replica URL is a key prefix whose history belongs to a single database, and per-file lifetime is the whole point: a directory-wide replicator cannot start when one namespace arrives and stop when that one is evicted.
Separate module on purpose ¶
hanzoai/replicate brings the AWS/GCS/Azure SDKs with it. Every consumer of hanzoai/orm would pay for that import even when it never replicates anything, so orm declares the seam and this module fills it: the dependency arrives with the capability, not before it.
Configuration ¶
REPLICATE_S3_ENDPOINT and friends, as every other hanzo service spells it (see replicate.AutoReplicate). With none of it set, and no explicit RemoteURL, Namespaces returns the plain local collection — the same construction path on a laptop and in a cluster, minus durability.
The constraint that does not go away ¶
One writer per namespace. Two nodes holding the same one open stream two histories to one prefix and the loser's writes are gone. Nothing here enforces that; the namespace is the shard key, so route each to one node.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Namespaces ¶ added in v0.1.1
Namespaces returns a collection whose files are durable in object storage.
It is db.NewNamespaces with the three durability seams filled in, and it returns the same *db.Namespaces, so callers see one type whether or not replication is configured.
Types ¶
type Config ¶
type Config[T io.Closer] struct { db.NamespacesConfig[T] // RemoteURL is the root the replicas live under: each database streams to // <RemoteURL>/<namespace>. Empty means "build it from the REPLICATE_S3_* // environment"; empty with no environment means local only. // // It is a replica URL rather than an endpoint because that is the value // replicate already speaks (s3://, gs://, abs://, file://…), so moving a // deployment's durable copies is a config change and not a code change. Only // s3 and file are linked in here — another scheme needs a blank import of // its backend package. // // It must not be node-scoped. A prefix carrying a hostname makes each node's // replicas invisible to every other node, which defeats the point: a // namespace evicted here has to be restorable there. RemoteURL string }
Config is a db.NamespacesConfig plus where the durable copies live.
Source Files