litefs

package
v1.44.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: BSD-3-Clause Imports: 7 Imported by: 0

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

View Source
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.

View Source
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)

See: https://fly.io/docs/litefs/primary/

Variables

This section is empty.

Functions

func IsCandidate added in v1.33.0

func IsCandidate(processGroup string) bool

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

func IsPrimaryAt(path string) bool

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

func IsPrimaryWithFallback(path string, envKey string) bool

IsPrimaryWithFallback detects primary status with a fallback for environments where LiteFS is not running (e.g., local development).

Detection order:

  1. If the primary file at path exists, this is a replica (return false).
  2. 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).
  3. 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.
  4. 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

func PosPath(dbPath string) string

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

func PrimaryHost(path string) string

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

func ReadPos(path string) (string, error)

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

func ValidateEnvFallback(envKey string) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL