litefs

package
v1.35.2 Latest Latest
Warning

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

Go to latest
Published: Sep 26, 2026 License: BSD-3-Clause Imports: 6 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 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(region, primaryRegion string) bool

IsCandidate reports whether LiteFS can elect this node as primary. It mirrors the lease rule in litefs.yml, `candidate: ${FLY_REGION == PRIMARY_REGION}`: region is FLY_REGION and primaryRegion is PRIMARY_REGION. When both values are empty (not on Fly.io), every node is a candidate. When only one is empty, LiteFS elects no node, so no node is 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_REGION and PRIMARY_REGION). A replica also sees no file while no node holds the lease, for example while the primary restarts during a deploy.
  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 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