Documentation
¶
Overview ¶
Package litefs provides utilities for detecting the role of the current node in a LiteFS cluster (primary vs replica) and for reading the replication position of a database.
Index ¶
- Constants
- func IsCandidate(processGroup string) bool
- func IsPrimaryAt(path string) bool
- func IsPrimaryWithFallback(path string, envKey string) bool
- func PosPath(dbPath string) string
- func PrimaryHost(path string) string
- func ReadPos(path string) (string, error)
- func ValidateEnvFallback(envKey string) error
Constants ¶
const CandidateProcessGroup = "primary"
CandidateProcessGroup is the Fly.io process group whose machines LiteFS can elect as primary. Its machines have a volume, in more than one region, so that a standby can take the lease when the primary is lost.
const PrimaryFile = "/litefs/.primary"
PrimaryFile is the standard LiteFS lease file path. This file exists ONLY on replica nodes and contains the primary's hostname. Its ABSENCE means this node IS the primary.
The semantics are inverted from what the filename suggests:
- .primary file EXISTS -> this node is a REPLICA (file contains the primary's address)
- .primary file ABSENT -> this node IS the PRIMARY (we hold the lease)
Variables ¶
This section is empty.
Functions ¶
func IsCandidate ¶ added in v1.33.0
IsCandidate reports whether LiteFS can elect this node as primary. It mirrors the lease rule in litefs.yml, `candidate: ${FLY_PROCESS_GROUP == "primary"}`: processGroup is FLY_PROCESS_GROUP. A node with no process group (not on Fly.io) is not a candidate.
func IsPrimaryAt ¶
IsPrimaryAt reports whether this node is the LiteFS primary by checking the given path for the lease file. Returns true when the file does NOT exist (absence = primary), false when it does exist (presence = replica).
This is a low-level primitive with no fallback handling; it is exported so the package's external test can exercise the lease-file semantics against arbitrary paths. Production code calls IsPrimaryWithFallback, which adds the fail-safe-to-replica path for ambiguous stat errors and the no-LiteFS env-var fallback.
func IsPrimaryWithFallback ¶
IsPrimaryWithFallback detects primary status with a fallback for environments where LiteFS is not running (e.g., local development).
Detection order:
- If the primary file at path exists, this is a replica (return false).
- If stat fails with anything other than "does not exist" (e.g. a flaky LiteFS FUSE mount returning EIO/EACCES/ENOTDIR), fail SAFE toward replica (return false) and log a WARN. A misclassified replica that declines primary duties is harmless; a misclassified primary runs destructive Schema.Create DDL (WithDropColumn/WithDropIndex).
- If the file is genuinely absent and the parent directory of path exists (LiteFS is mounted), this is the primary only if LiteFS can elect it (IsCandidate of FLY_PROCESS_GROUP). A replica also sees no file while no node holds the lease, for example while the primary restarts during a deploy. In that gap every candidate reads as primary; LiteFS still refuses their writes, and a running sync cycle stops at the next demotion check.
- If neither exists (no LiteFS), fall back to the environment variable identified by envKey parsed as a boolean. Defaults to true if the env var is unset, matching the common local-dev expectation (single node = primary).
func PosPath ¶ added in v1.28.3
PosPath returns the path of the LiteFS position file for the database at dbPath. LiteFS exposes one "<db>-pos" file next to each database in the FUSE mount.
func PrimaryHost ¶ added in v1.42.0
PrimaryHost returns the hostname of the LiteFS primary as LiteFS writes it to the lease file at path on a replica. On Fly.io the hostname is the machine ID of the primary, so it can address a fly-replay to the primary machine. It returns "" when the file is absent or unreadable: this node is the primary, or no node holds the lease.
func ReadPos ¶ added in v1.28.3
ReadPos returns the replication position of a LiteFS database, read from its "-pos" file at path. The position changes on every committed transaction that LiteFS applies to the database, on the primary and on each replica.
LiteFS v0.5 renders the file in fuse/pos_node.go as TXID and PostApplyChecksum separated by "/", each formatted %016x, with a trailing newline. ReadPos requires exactly that shape and returns it without the newline. Each call opens and reads the file again, because LiteFS generates the content on each read.
A missing file returns an error that matches fs.ErrNotExist.
func ValidateEnvFallback ¶ added in v1.23.0
ValidateEnvFallback checks that the environment fallback variable, if set, parses as a boolean. Call once at startup so an operator typo in PDBPLUS_IS_PRIMARY fails fast with a clear message instead of being silently coerced into a role at every scheduler tick. Unset is valid (the documented "default primary" local-dev behaviour).
Types ¶
This section is empty.