LiteFS

https://github.com/superfly/litefs
Admin
LiteFS is a FUSE-based file system that replicates SQLite databases across a cluster of machines by...
Tokens:163,100
Snippets:1,075
Trust Score:9.4
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### MountCommand.initEnvironment usage example

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/environment.md

Usage example from MountCommand.initEnvironment that installs the Fly environment only when running on Fly, then logs the detected environment type.

```go
func (c *MountCommand) initEnvironment(ctx context.Context) {
	if fly.Available() {
		c.Store.Environment = fly.NewEnvironment()
	}

	if typ := c.Store.Environment.Type(); typ != "" {
		slog.Info("host environment detected", slog.String("type", typ))
	}
}
```

--------------------------------

### Store usage example

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/store.md

Usage example for creating and opening a Store as a candidate node. It sets up the client and leaser, opens the store, waits for readiness, and iterates over databases to print their names and positions.

```go
import "github.com/superfly/litefs"

store := litefs.NewStore("/var/lib/litefs", true) // candidate node
store.Client = http.NewClient()
store.Leaser = consul.NewLeaser("http://consul:8500", "litefs/primary", hostname, advertiseURL)
if err := store.Leaser.Open(); err != nil {
	panic(err)
}
if err := store.Open(); err != nil {
	panic(err)
}
defer func() { _ = store.Close() }()

// Wait until the node has sync'd with the cluster.
select {
case <-store.ReadyCh():
}

for _, db := range store.DBs() {
	print("db", db.Name(), "pos", db.Pos().String())
}
```

--------------------------------

### Export and Promote usage examples

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-client.md

Usage examples: first exports a database from the admin API, saving to a file; second attempts promotion, handling litefs.ErrNotEligible.

```go
client := http.NewClient()
r, err := client.Export(ctx, "http://localhost:20202", "myapp")
if err != nil {
	panic(err)
}
defer func() { _ = r.Close() }()

f, err := os.Create("/tmp/myapp.db")
if err != nil {
	panic(err)
}
defer func() { _ = f.Close() }()

if _, err := io.Copy(f, r); err != nil {
	panic(err)
}
if err := f.Sync(); err != nil {
	panic(err)
}
```

```go
client := http.NewClient()
if err := client.Promote(ctx, "http://localhost:20202"); err != nil {
	if err == litefs.ErrNotEligible {
		log.Printf("node cannot be promoted (not a candidate)")
	} else {
		log.Printf("promote failed: %s", err)
	}
}
```

--------------------------------

### Programmatic setup of FileBackupClient

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/backup-client.md

Programmatic setup of the file backup client. Creates a client, opens it, and assigns it to the store along with backup delay and full sync interval settings.

```go
client := litefs.NewFileBackupClient("/var/backups/litefs")
if err := client.Open(); err != nil {
	panic(err)
}
store.BackupClient = client
store.BackupDelay = 1 * time.Second
store.BackupFullSyncInterval = 10 * time.Second
```

--------------------------------

### Configure and start HTTP proxy server in Go

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-proxy.md

Wired from `litefs mount` (`mount_linux.go:528`). Configures the HTTP proxy server with target, database name, address, and various timeouts, then starts listening and serving.

```go
server := http.NewProxyServer(store)
server.Target = c.Config.Proxy.Target      // "localhost:8081"
server.DBName = c.Config.Proxy.DB          // "my.db"
server.Addr = c.Config.Proxy.Addr          // ":8080"
server.MaxLag = c.Config.Proxy.MaxLag
server.Debug = c.Config.Proxy.Debug
server.Passthroughs = passthroughs
server.AlwaysForward = alwaysForward
server.PrimaryRedirectTimeout = c.Config.Proxy.PrimaryRedirectTimeout
server.ReadTimeout = c.Config.Proxy.ReadTimeout
server.ReadHeaderTimeout = c.Config.Proxy.ReadHeaderTimeout
server.WriteTimeout = c.Config.Proxy.WriteTimeout
server.IdleTimeout = c.Config.Proxy.IdleTimeout

if err := server.Listen(); err != nil {
	return err
}
server.Serve()
```

--------------------------------

### Usage example

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/consul.md

Usage example for creating a Consul leaser and handling lease acquisition errors.

```APIDOC
## Usage example

### Description
Shows how to instantiate a Consul leaser and handle lease acquisition races.

### Instantiation
```go
leaser := consul.NewLeaser(c.Config.Lease.Consul.URL, c.Config.Lease.Consul.Key, hostname, advertiseURL)
if v := c.Config.Lease.Consul.TTL; v > 0 {
	leaser.TTL = v
}
if v := c.Config.Lease.Consul.LockDelay; v > 0 {
	leaser.LockDelay = v
}
if err := leaser.Open(); err != nil {
	return fmt.Errorf("cannot connect to consul: %w", err)
}
c.Leaser = leaser
```

### Acquisition Error Handling
```go
lease, err := s.Leaser.Acquire(ctx)
if err == litefs.ErrPrimaryExists {
	// another node won; refetch primary info and connect as replica
} else if err != nil {
	return nil, info, fmt.Errorf("acquire lease: %w", err)
}
```
```

--------------------------------

### Create and run HTTP server

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-server.md

Shows how to instantiate the server with a store and address, set the snapshot timeout, listen, serve, and close. The example prints the server URL and defers closing.

```go
server := http.NewServer(store, ":20202")
server.SnapshotTimeout = 30 * time.Second
if err := server.Listen(); err != nil {
	panic(err)
}
server.Serve()
print("listening on", server.URL())
defer func() { _ = server.Close() }()
```

--------------------------------

### Usage examples for insert and query modes

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/bench.md

Two shell commands demonstrating how to run litefs-bench in insert and query modes against a LiteFS-mounted database.

```sh
# Continuous inserts from replica nodes (uses halt locks for writes)
litefs-bench insert -mode insert -iter 0 -journal-mode wal /litefs/my.db
```

```sh
# Short SELECTs against the same database
litefs-bench query -mode query -max-rows-per-iter 20 /litefs/my.db
```

--------------------------------

### Wiring BackupClient in MountCommand.initStoreBackupClient

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/lfsc.md

Usage example wired by MountCommand.initStoreBackupClient (mount_linux.go:438). Sets the default endpoint URL to https://litefs.fly.io if not configured, parses it, creates the client, sets Cluster and AuthToken from config, calls Open(), and assigns the client to the store. Can also be configured via environment variables LITEFS_CLOUD_TOKEN (auth) and LITEFS_CLOUD_ENDPOINT (URL override).

```go
// Default endpoint URL, unless already configured.
if c.Config.Backup.URL == "" {
	c.Config.Backup.URL = "https://litefs.fly.io"
}

u, err := url.Parse(c.Config.Backup.URL)
if err != nil {
	return fmt.Errorf("cannot parse liteserver backup URL: %w", err)
}

client := lfsc.NewBackupClient(c.Store, *u)
client.Cluster = c.Config.Backup.Cluster
client.AuthToken = c.Config.Backup.AuthToken

if err := client.Open(); err != nil {
	return fmt.Errorf("open litefs cloud backup client: %w", err)
}
c.Store.BackupClient = client
```

--------------------------------

### GET /export

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-server.md

Exports a database snapshot. Requires a `name` query parameter.

```APIDOC
## GET /export

### Description
Exports a database snapshot. Requires `name` (400), context must not be done (503). `store.DB(name)` nil → 404 with `ErrDatabaseNotFound`. Streams `db.Export(r.Context(), w)`, errors → 500. Logs `"snapshot successfully exported @ <pos>"` on success.

### Method
GET

### Endpoint
/export

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the database to export.

### Response
#### Success Response (200)
Streams the database export. No response body details provided.

#### Error Responses
- **400** - Missing `name` query parameter.
- **503** - Context done.
- **404** - Database not found.
- **500** - Export error.
```

--------------------------------

### Wiring FileSystem in litefs mount

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/fuse-filesystem.md

Usage example from litefs mount (mount_linux.go:499). Creates the file system, sets AllowOther and Debug from config, mounts it, and attaches it to the store as the invalidator. Returns an error if mounting fails.

```go
fsys := fuse.NewFileSystem(c.Config.FUSE.Dir, c.Store)
fsys.AllowOther = c.Config.FUSE.AllowOther
fsys.Debug = c.Config.FUSE.Debug
if err := fsys.Mount(c.skipUnmount); err != nil {
	return fmt.Errorf("cannot open file system: %s", err)
}

// Attach file system to store so it can invalidate the page cache.
c.Store.Invalidator = fsys
c.FileSystem = fsys
```

--------------------------------

### Compiling proxy passthrough expressions

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-helpers.md

Usage example from MountCommand.runProxyServer: compiles each proxy passthrough expression from the configuration and appends the resulting regex to a slice. On error, it returns a formatted error message.

```go
for _, s := range c.Config.Proxy.Passthrough {
	re, err := http.CompileMatch(s)
	if err != nil {
		return fmt.Errorf("cannot parse proxy passthrough expression: %q", s)
	}
	passthroughs = append(passthroughs, re)
}
```

--------------------------------

### LiteFS CLI usage examples: mount, import, run

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/cli.md

Shows three common LiteFS commands: mounting an app with FUSE and Consul leases, importing a database from a file, and running a one-off migration on a replica. Each command uses the litefs CLI with specific flags and arguments.

```sh
# Run an app with FUSE + Consul leases
litefs mount --config /etc/litefs.yml -- /usr/local/bin/myapp

# Replace the "myapp" database from a file
litefs import --url http://localhost:20202 --name myapp ./myapp.db

# Run a one-off migration on a replica
litefs run --with-halt-lock-on /litefs/myapp -- sqlite3 /litefs/myapp "PRAGMA optimize"
```

--------------------------------

### GET /export?name=<name>

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-client.md

Exports a database as a stream. Returns 404 if the database is not found.

```APIDOC
## GET /export?name=<name>

### Description
Exports a database as a stream. Returns 404 if the database is not found.

### Method
GET

### Endpoint
/export

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the database to export.

### Response
#### Success Response (200)
- **body** (io.ReadCloser) - The database file content. Caller must close the body.

#### Error Response (404)
- **litefs.ErrDatabaseNotFound** - The database was not found.
```

--------------------------------

### Generate and validate cluster ID and parse node ID

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/litefs.md

Shows how to generate and validate a cluster ID, and parse and format a node ID using the low-level helpers from the litefs package. The example prints the formatted node ID, which matches the input string.

```go
import "github.com/superfly/litefs"

clusterID := litefs.GenerateClusterID()
if err := litefs.ValidateClusterID(clusterID); err != nil {
	panic(err)
}
nodeID := litefs.ParseNodeID("DEADBEEFDEADBEEF")
print(litefs.FormatNodeID(nodeID)) // -> "DEADBEEFDEADBEEF"
```

--------------------------------

### GET /events

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-server.md

Subscribes to store events and streams JSON-encoded events.

```APIDOC
## GET /events

### Description
Subscribes to store events. Sets `Content-Type: application/json`, writes HTTP 200, then streams JSON-encoded `Event` values (`json.NewEncoder`), flushing after each. Exits on client context done or when the subscriber channel is closed (buffer exceeded).

### Method
GET

### Endpoint
/events

### Response
#### Success Response (200)
Streams JSON-encoded `Event` values.

#### Response Example
{
  "type": "...",
  "data": {}
}
```

--------------------------------

### Leaser.Open

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/consul.md

Initializes the Consul client and registers the node. Parses the Consul URL, requires Key, hostname, and advertiseURL, and sets up the client with basic auth from URL userinfo.

```APIDOC
## Leaser.Open

### Description
Initializes the Consul client and registers the node. Parses the Consul URL, requires Key, hostname, and advertiseURL, and sets up the client with basic auth from URL userinfo.

### Signature
`func (l *Leaser) Open() error`

### Parameters
None.

### Returns
- **error** - An error if initialization fails.
```

--------------------------------

### GET /info

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-server.md

Retrieves information about the current node's status and primary information.

```APIDOC
## GET /info

### Description
Builds `litefs.NodeInfo` from the store: `ClusterID`, `IsPrimary`, `Candidate`, `Path`, and `Primary.Hostname` (own hostname when primary, else the known primary's hostname). Marshals with `json.MarshalIndent(info, "", "  ")`.

### Method
GET

### Endpoint
/info

### Response
#### Success Response (200)
- **ClusterID** (string) - The cluster ID.
- **IsPrimary** (boolean) - Whether this node is the primary.
- **Candidate** (boolean) - Whether this node is a candidate for primary.
- **Path** (string) - The path to the store.
- **Primary.Hostname** (string) - The hostname of the primary (own hostname when primary, else the known primary's hostname).

#### Response Example
{
  "ClusterID": "...",
  "IsPrimary": true,
  "Candidate": true,
  "Path": "/path/to/store",
  "Primary": {
    "Hostname": "node1"
  }
}
```

--------------------------------

### FileBackupClient struct and constructor

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/backup-client.md

Shows the FileBackupClient struct and its constructor and Open method signatures. Open resolves the path to absolute and creates the directory with MkdirAll, returning an error "backup path required" if the path is empty.

```go
type FileBackupClient struct {
	mu   sync.Mutex
	path string
}

func NewFileBackupClient(path string) *FileBackupClient
func (c *FileBackupClient) Open() (err error)
```

--------------------------------

### NewProxyServer(store *litefs.Store) *ProxyServer

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-proxy.md

Creates a new ProxyServer instance with the given store. The returned server must be configured by setting exported fields before calling Listen().

```APIDOC
## NewProxyServer(store *litefs.Store) *ProxyServer

### Description
Creates a new ProxyServer instance with the given store. The returned server must be configured by setting exported fields before calling Listen().

### Method
Constructor

### Signature
```go
func NewProxyServer(store *litefs.Store) *ProxyServer
```

### Parameters
- **store** (*litefs.Store) - Required - The LiteFS store used for TXID consistency tracking.

### Returns
- **\*ProxyServer** - A new ProxyServer instance with default configuration.

### Notes
- Exported fields must be set before calling Listen().
- Required fields: Target, DBName, Addr.
- Defaults are provided by the Default* constants.
- HTTPTransport is pre-configured with proxy-from-environment, 30s dial timeout with retries on ECONNREFUSED, HTTP/2 forced, 100 max idle conns, 90s idle conn timeout, 10s TLS handshake timeout, and 1s expect-continue timeout.
```

--------------------------------

### NodeInfo

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/litefs.md

Represents information about a node in the LiteFS cluster. Produced by the `GET /info` endpoint and consumed by `http.Client.Info`.

```APIDOC
## NodeInfo

### Description
Represents information about a node in the LiteFS cluster. Produced by the `GET /info` endpoint and consumed by `http.Client.Info`.

### Fields
- **ClusterID** (string) - Optional - The cluster ID.
- **IsPrimary** (bool) - Required - If true, the node is currently primary.
- **Candidate** (bool) - Required - If true, the node is eligible to be primary.
- **Path** (string) - Required - The data directory path.
- **Primary.Hostname** (string) - Required - The hostname of the primary node.

### JSON Example
```json
{
  "clusterID": "...",
  "isPrimary": true,
  "candidate": true,
  "path": "/data",
  "primary": {
    "hostname": "..."
  }
}
```
```

--------------------------------

### Configure Store with StaticLeaser for replica and primary

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/lease.md

Shows how to configure a Store with a StaticLeaser for both replica and primary roles in a static-lease cluster. The primary must provide its URL; the replica uses an empty string. After setting the leaser, the store is opened and any error causes a panic.

```go
import "github.com/superfly/litefs"

// A replica in a static-lease cluster:
store.Leaser = litefs.NewStaticLeaser(false, "db-replica-1", "")
// A primary in a static-lease cluster:
store.Leaser = litefs.NewStaticLeaser(true, "db-primary", "http://db-primary:20202")

if err := store.Open(); err != nil {
	panic(err)
}
```

--------------------------------

### FetchSnapshot

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/lfsc.md

Fetches a snapshot from the LFSC API via GET /db/snapshot, returning the response body reader.

```APIDOC
## FetchSnapshot

### Description
Fetches a snapshot from the LFSC API via GET /db/snapshot, returning the response body reader.

### Method
GET

### Endpoint
/db/snapshot?db=<name>[&cluster=<name>]

### Parameters
#### Query Parameters
- **db** (string) - Required - The database name.
- **cluster** (string) - Optional - The cluster name.

### Returns
- **io.ReadCloser** - The response body reader.
- **error** - Error if the request fails.

```

--------------------------------

### GET /export

Source: https://github.com/superfly/litefs/blob/main/_autodocs/endpoints.md

Downloads the current database file bytes. This endpoint streams the raw database file to the client.

```APIDOC
## GET /export

### Description
Downloads the current database file bytes. This endpoint streams the raw database file to the client.

### Method
GET

### Endpoint
`/export?name=<db>`

### Parameters
#### Query Parameters
- **name** (string) - Required - Database name

### Response
#### Success Response (200)
Raw database bytes streamed

#### Error Responses
- **400** - Name missing
- **503** - Context done
- **404** - Database doesn't exist
- **500** - Streaming error
```

--------------------------------

### PosMap

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/lfsc.md

Fetches the position map from the LFSC API via GET /pos, optionally filtered by cluster name.

```APIDOC
## PosMap

### Description
Fetches the position map from the LFSC API via GET /pos, optionally filtered by cluster name.

### Method
GET

### Endpoint
/pos[?cluster=<name>]

### Parameters
#### Query Parameters
- **cluster** (string) - Optional - The cluster name to filter by.

### Returns
- **map[string]ltx.Pos** - The decoded JSON position map.
- **error** - Error if the request fails.

```

--------------------------------

### EventSubscriber

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/store.md

EventSubscriber provides a channel for consuming LiteFS events. Use Stop() to remove the subscriber and C() to get the event channel.

```APIDOC
## EventSubscriber

### Description
EventSubscriber provides a channel for consuming LiteFS events. Use Stop() to remove the subscriber and C() to get the event channel.

### Methods
- **Stop()** - Removes the subscriber.
- **C() <-chan Event** - Returns the event channel.

### Event Types
- `EventTypeInit` = "init"
- `EventTypeTx` = "tx"
- `EventTypePrimaryChange` = "primaryChange"

### Event Structure
- **Type** (string) - Event type.
- **DB** (string) - Database name (optional).
- **Data** (any) - Event data payload.

### Event Data Payloads

#### InitEventData
- **IsPrimary** (bool) - Whether the node is primary.
- **Hostname** (string) - Hostname (optional).

#### TxEventData
- **TXID** (ltx.TXID) - Transaction ID.
- **PostApplyChecksum** (ltx.Checksum) - Post-apply checksum.
- **PageSize** (uint32) - Page size.
- **Commit** (uint32) - Commit timestamp.
- **Timestamp** (time.Time) - Event timestamp.

#### PrimaryChangeEventData
- **IsPrimary** (bool) - Whether the node is primary.
- **Hostname** (string) - Hostname (optional).

### Notes
Events are consumed by `GET /events` (see endpoints.md).
```

--------------------------------

### Snapshot and export a database with litefs.Store

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/db.md

Shows how to load the global LiteFS store, retrieve a database by name, and write a snapshot or export raw bytes. Handles errors by logging and closing the server on snapshot failure.

```go
import "github.com/superfly/litefs"

// Snapshot a database to a writer (used by backup & export paths).
store := litefs.GlobalStore.Load().(*litefs.Store)
if db := store.DB("myapp"); db != nil {
	header, trailer, err := db.WriteSnapshotTo(ctx, dst)
	if err != nil {
		log.Printf("snapshot failed: %s", err)
		server.Close()
		return
	}
	print("snapshot up to tx", header.MaxTXID.String())

	// Or export the raw database bytes:
	pos, err := db.Export(ctx, dst)
	if err != nil {
		log.Printf("export failed: %s", err)
	}
}
```

--------------------------------

### GET /info

Source: https://github.com/superfly/litefs/blob/main/_autodocs/endpoints.md

Retrieves node metadata for the LiteFS node. This endpoint is used by the CLI `litefs run` command to obtain node information.

```APIDOC
## GET /info

### Description
Retrieves node metadata for the LiteFS node. This endpoint is used by the CLI `litefs run` command to obtain node information.

### Method
GET

### Endpoint
`/info`

### Parameters
None

### Response
#### Success Response (200)
- **clusterID** (string) - Cluster ID (omitted when empty)
- **isPrimary** (bool) - Node currently primary
- **candidate** (bool) - Eligible to become primary
- **path** (string) - Data directory
- **primary.hostname** (string) - Own hostname when primary, else known primary's

#### Response Example
```json
{
  "clusterID": "...",
  "isPrimary": true,
  "candidate": true,
  "path": "/data",
  "primary": {
    "hostname": "node1"
  }
}
```

#### Error Responses
- **500** - Marshal/write failure
```

--------------------------------

### Assert WAL index structure sizes in init()

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/litefs.md

Runs at package initialization to assert the expected sizes of the SQLite WAL index structures walIndexHdr and walCkptInfo. These compile-time/runtime checks ensure the struct layouts match the on-disk format.

```go
func init() {
	assert(unsafe.Sizeof(walIndexHdr{}) == 48, "invalid walIndexHdr size")
	assert(unsafe.Sizeof(walCkptInfo{}) == 40, "invalid walCkptInfo size")
}
```

--------------------------------

### Instantiate leaser in MountCommand.initConsul

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/consul.md

Shows how to create a new Consul leaser, set optional TTL and LockDelay, open the connection, and assign it to the command. Used in MountCommand.initConsul at mount_linux.go:393.

```go
leaser := consul.NewLeaser(c.Config.Lease.Consul.URL, c.Config.Lease.Consul.Key, hostname, advertiseURL)
if v := c.Config.Lease.Consul.TTL; v > 0 {
	leaser.TTL = v
}
if v := c.Config.Lease.Consul.LockDelay; v > 0 {
	leaser.LockDelay = v
}
if err := leaser.Open(); err != nil {
	return fmt.Errorf("cannot connect to consul: %w", err)
}
c.Leaser = leaser
```

--------------------------------

### NewLeaser

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/consul.md

Constructs a new Consul-backed Leaser with the given Consul URL, key, hostname, and advertise URL.

```APIDOC
## NewLeaser

### Description
Constructs a new Consul-backed Leaser with the given Consul URL, key, hostname, and advertise URL.

### Signature
`func NewLeaser(consulURL, key, hostname, advertiseURL string) *Leaser`

### Parameters
- **consulURL** (string) - Required - The URL of the Consul server.
- **key** (string) - Required - The Consul KV key used to acquire the lock.
- **hostname** (string) - Required - The hostname of the node.
- **advertiseURL** (string) - Required - The advertise URL of the node.

### Returns
- **\*Leaser** - A new Leaser instance.
```

--------------------------------

### NewStore

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/store.md

Constructs a new Store instance with the given internal data directory path and candidate flag. The candidate flag controls whether the node may become primary. Defaults are set for various configuration fields.

```APIDOC
## NewStore

### Description
Constructs a new Store instance. The `path` is the internal data directory; `candidate` controls whether the node may become primary. Defaults are set at construction.

### Signature
```go
func NewStore(path string, candidate bool) *Store
```

### Parameters
- **path** (string) - Required - The internal data directory path.
- **candidate** (bool) - Required - Whether the node may become primary.

### Returns
- **\*Store** - A pointer to the newly created Store instance.

### Configuration Fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `OS` | `OS` | `&internal.SystemOS{}` | OS interface for all file operations |
| `Exit` | `func(int)` | `os.Exit` | called to fatally exit on commit/apply errors |
| `ReconnectDelay` | `time.Duration` | `DefaultReconnectDelay` = `1 * time.Second` | wait after primary disconnect |
| `DemoteDelay` | `time.Duration` | `DefaultDemoteDelay` = `10 * time.Second` | wait after manual demotion |
| `Retention` | `time.Duration` | `DefaultRetention` = `10 * time.Minute` | LTX file retention |
| `RetentionMonitorInterval` | `time.Duration` | `DefaultRetentionMonitorInterval` = `1 * time.Minute` | retention sweep interval (`<=0` disables monitor) |
| `HaltAcquireTimeout` | `time.Duration` | `DefaultHaltAcquireTimeout` = `10 * time.Second` | HALT lock acquisition timeout |
| `HaltLockTTL` | `time.Duration` | `DefaultHaltLockTTL` = `30 * time.Second` | HALT lock TTL |
| `HaltLockMonitorInterval` | `time.Duration` | `DefaultHaltLockMonitorInterval` = `5 * time.Second` | lock expiry check interval |
| `BackupDelay` | `time.Duration` | `DefaultBackupDelay` = `1 * time.Second` | batching delay before backup write |
| `BackupFullSyncInterval` | `time.Duration` | `DefaultBackupFullSyncInterval` = `10 * time.Second` | position-map refresh interval |
| `Compress` | `bool` | `false` | set LTX `HeaderFlagCompressLZ4` |
| `Environment` | `Environment` | `&nopEnvironment{}` | host integration |
| `Invalidator` | `Invalidator` | `nil` | page-cache invalidation callback |
| `Client` | `Client` | `nil` | replication client (set by CLI to `http.NewClient()`) |
| `Leaser` | `Leaser` | `nil` (required before `Open()`) | leader-election backend |
| `BackupClient` | `BackupClient` | `nil` | backup service client |
| `DatabaseFilter` | `[]string` | `nil` | databases to replicate (replicas only) |
| `StrictVerify` | `bool` | `false` | verify full-database checksum after every commit (testing) |
```

--------------------------------

### CompileMatch

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-helpers.md

Compiles a user-supplied path expression into a regular expression. Special regexp characters are escaped with regexp.QuoteMeta, escaped asterisks are converted to .*, and the whole expression is anchored with ^…$. Example expressions: "/debug/*", "*.png".

```APIDOC
## CompileMatch

### Description
Compiles a user-supplied path expression into a regular expression. Special regexp characters are escaped with regexp.QuoteMeta, escaped asterisks are converted to .*, and the whole expression is anchored with ^…$. Example expressions: "/debug/*", "*.png".

### Function Signature
func CompileMatch(s string) (*regexp.Regexp, error)

### Parameters
- **s** (string) - Required - The path expression to compile.

### Returns
- ***regexp.Regexp** - The compiled regular expression.
- **error** - Returns a regexp compile error if the pattern is invalid.

### Errors
- **regexp compile error** - Returned on invalid patterns. MountCommand.runProxyServer converts this to "cannot parse proxy passthrough expression: %q" or "cannot parse proxy always-forward expression: %q" during startup.
```

--------------------------------

### Streaming client usage of WritePosMapTo

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-helpers.md

Usage example from the streaming client: writes the position map to a buffer, creates a POST request to the stream endpoint, sets the node ID header, and sends it. This is the replica's "what do you have?" request.

```go
var buf bytes.Buffer
if err := WritePosMapTo(&buf, posMap); err != nil {
	return nil, fmt.Errorf("cannot write pos map: %w", err)
}
req, err := http.NewRequest("POST", u.String(), &buf)
req = req.WithContext(ctx)
req.Header.Set(HeaderNodeID, litefs.FormatNodeID(nodeID))

resp, err := c.HTTPClient.Do(req)
```

--------------------------------

### Lifecycle

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/store.md

Methods to manage the store lifecycle: open, close, readiness, demotion, handoff, and recovery.

```APIDOC
## Lifecycle

```go
func (s *Store) Open() error
func (s *Store) Close() (retErr error)
func (s *Store) ReadyCh() chan struct{}
func (s *Store) Demote()
func (s *Store) Handoff(ctx context.Context, nodeID uint64) error
func (s *Store) Recover(ctx context.Context) (err error)
```

- `Open` (`store.go:262`) requires `Leaser` to be set; creates the data dir,
  loads the persisted cluster ID, opens all databases under `DBDir()`, then
  starts background goroutines: `monitorLease`, `monitorHaltLock`, and (if
  `RetentionMonitorInterval > 0`) `monitorRetention`.
- `Close` cancels with `ErrStoreClosed`, waits on the errgroup, then releases
  any outstanding remote HALT locks.
- `ReadyCh` closes once the node becomes primary or connects to the primary.
- `Handoff` sends the current lease to a connected replica (by node ID);
  errors if not primary or the target is not subscribed.
- `Recover` runs `db.Recover()` on every database (used on primary/replica
  state changes).
```

--------------------------------

### ImportCommand struct and constructor

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/cli.md

Defines the ImportCommand struct and its constructor. The Run method streams a local database file via client.Import(ctx, c.URL, c.Name, f). The uploaded database is not validated for integrity; run PRAGMA integrity_check first.

```go
type ImportCommand struct {
	URL string
	Name string
	Path string
}

func NewImportCommand() *ImportCommand
```

--------------------------------

### POST /import

Source: https://github.com/superfly/litefs/blob/main/_autodocs/endpoints.md

Replaces or creates a database from a raw SQLite file. This endpoint is primary-only and requires the node to be the current primary.

```APIDOC
## POST /import

### Description
Replaces or creates a database from a raw SQLite file. This endpoint is primary-only and requires the node to be the current primary.

### Method
POST

### Endpoint
`/import?name=<db>`

### Parameters
#### Query Parameters
- **name** (string) - Required - Database name

#### Request Body
Raw database file bytes (the request body)

### Response
#### Success Response (200)
No body

#### Error Responses
- **400** - `name` missing
- **503** - Node is not (or lost) primary
- **500** - Create/import failure
```

--------------------------------

### NodeInfo struct for cluster node state

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/litefs.md

NodeInfo describes a LiteFS node's state, including cluster ID, primary status, candidate eligibility, data directory path, and the primary node's hostname. It is produced by GET /info and consumed by http.Client.Info.

```go
type NodeInfo struct {
	ClusterID string `json:"clusterID,omitempty"` // cluster ID
	IsPrimary bool   `json:"isPrimary"`           // if true, node is currently primary
	Candidate bool   `json:"candidate"`           // if true, node is eligible to be primary
	Path      string `json:"path"`                // data directory

	Primary struct {
		Hostname string `json:"hostname"`
	} `json:"primary"`
}
```

--------------------------------

### BackupClient Interface & FileBackupClient

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/backup-client.md

Documentation for the BackupClient interface and its FileBackupClient implementation, including methods, usage, and error handling.

```APIDOC
## BackupClient Interface

### Description
Defines the contract for a long-term storage sink for replicated LTX files. When configured, the primary compacts pending LTX files and pushes them to the backup service; on a position mismatch, the primary restores the database from the backup snapshot.

### Methods

#### URL
- **Signature**: `URL() string`
- **Description**: Returns the URL of the backup service.

#### PosMap
- **Signature**: `PosMap(ctx context.Context) (map[string]ltx.Pos, error)`
- **Description**: Returns the replication position for all databases on the backup service.

#### WriteTx
- **Signature**: `WriteTx(ctx context.Context, name string, r io.Reader) (hwm ltx.TXID, err error)`
- **Description**: Writes an LTX file to the backup service. The file must be contiguous with the latest LTX file on the backup service or else it will return an `ltx.PosMismatchError`. Returns the high-water mark that indicates it is safe to remove LTX files before that transaction ID.

#### FetchSnapshot
- **Signature**: `FetchSnapshot(ctx context.Context, name string) (io.ReadCloser, error)`
- **Description**: Requests a full snapshot of the database as it exists on the backup service. This should be used if the LiteFS node has become out of sync with the backup service.

### Implementations

| Implementation | Constructed by | Where |
|----------------|----------------|-------|
| `FileBackupClient` | `litefs.NewFileBackupClient(path)` | `backup_client.go` (reference implementation, mostly for testing) |
| `lfsc.BackupClient` | `lfsc.NewBackupClient(store, url)` | `api-reference/lfsc.md` (LiteFS Cloud) |

## FileBackupClient

### Description
A reference implementation of `BackupClient` that stores LTX files on the local filesystem. Layout on disk: `<path>/<db>/<min>-<max>.ltx`.

### Constructor

#### NewFileBackupClient
- **Signature**: `func NewFileBackupClient(path string) *FileBackupClient`
- **Description**: Creates a new `FileBackupClient` with the given path.

### Methods

#### Open
- **Signature**: `func (c *FileBackupClient) Open() (err error)`
- **Description**: Resolves the path to absolute and `MkdirAll`s it; errors `"backup path required"` when empty.

#### URL
- **Signature**: `func (c *FileBackupClient) URL() string`
- **Description**: Returns a `file://` URL of the path.

#### PosMap
- **Signature**: `func (c *FileBackupClient) PosMap(ctx context.Context) (map[string]ltx.Pos, error)`
- **Description**: Returns the position of every database directory (max `.ltx` file per dir, verified via `ltx.NewDecoder`).

#### WriteTx
- **Signature**: `func (c *FileBackupClient) WriteTx(ctx context.Context, name string, r io.Reader) (hwm ltx.TXID, err error)`
- **Description**: Writes the LTX stream to a temp file, verifies with the LTX decoder, atomically renames; returns `ltx.NewPosMismatchError(pos)` when not contiguous.

#### FetchSnapshot
- **Signature**: `func (c *FileBackupClient) FetchSnapshot(ctx context.Context, name string) (_ io.ReadCloser, retErr error)`
- **Description**: Compacts all `.ltx` files into a snapshot stream; `os.ErrNotExist` if the database has no LTX files.

### Usage Example

Wiring via `litefs mount` config (`backup.type: "file"`):

```yaml
backup:
  type: "file"
  path: "/mnt/backup/litefs"
```

Programmatically:

```go
client := litefs.NewFileBackupClient("/var/backups/litefs")
if err := client.Open(); err != nil {
	panic(err)
}
store.BackupClient = client
store.BackupDelay = 1 * time.Second
store.BackupFullSyncInterval = 10 * time.Second
```

Error handling for position mismatch (as done in `Store.streamBackupDB`):

```go
var pmErr *ltx.PosMismatchError
hwm, err := s.BackupClient.WriteTx(ctx, name, pr)
if errors.As(err, &pmErr) {
	// Restore from the backup snapshot; the backup is the data authority.
	newPos, err = s.restoreDBFromBackup(ctx, name)
	if err != nil {
		return ltx.Pos{}, fmt.Errorf("restore from backup error (%q): %s", name, err)
	}
}
db.SetHWM(hwm)
```

The returned high-water mark becomes `DB.HWM()`; `DB.EnforceRetention` only deletes LTX files older than the retention window **and** below the HWM when a backup client is configured.
```

--------------------------------

### BackupClient struct and NewBackupClient constructor

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/lfsc.md

Defines the BackupClient struct and constructor. The struct holds the store (for cluster ID), base URL, optional cluster name, auth token, HTTP client, and internal LFSC instance ID. NewBackupClient keeps only scheme and host from the provided URL.

```go
var _ litefs.BackupClient = (*BackupClient)(nil)

type BackupClient struct {
	store   *litefs.Store // store, used for cluster ID
	baseURL url.URL       // remote LiteFS Cloud URL

	// Name of cluster to replicate as.
	// This is typically set on the auth token and does not need to be set manually.
	Cluster string

	// Authentication field passed in via the "Authorization" HTTP header.
	AuthToken string

	HTTPClient *http.Client

	// ID of the LFSC instance that handles this cluster.
	lfscInstanceID string
}

func NewBackupClient(store *litefs.Store, u url.URL) *BackupClient
```

--------------------------------

### Server Lifecycle Methods

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-server.md

Methods to manage the HTTP server lifecycle: Listen, Serve, Close, Port, and URL.

```APIDOC
## Listen

### Description
Binds the TCP listener to the configured address.

### Method
Listen

### Signature
`func (s *Server) Listen() (err error)`

### Parameters
None

### Returns
- **err** (error) - Error if binding fails.

## Serve

### Description
Starts serving in a background goroutine. Blocks the caller's listener.

### Method
Serve

### Signature
`func (s *Server) Serve()`

### Parameters
None

### Returns
None

## Close

### Description
Closes the listener and HTTP server, cancels with ErrServerClosed, and waits for the errgroup.

### Method
Close

### Signature
`func (s *Server) Close() (err error)`

### Parameters
None

### Returns
- **err** (error) - Error if closing fails.

## Port

### Description
Returns the actual bound port. Returns 0 before Listen is called.

### Method
Port

### Signature
`func (s *Server) Port() int`

### Parameters
None

### Returns
- **int** - The bound port number.

## URL

### Description
Returns the full base URL of the server, e.g., `http://localhost:20202`.

### Method
URL

### Signature
`func (s *Server) URL() string`

### Parameters
None

### Returns
- **string** - The base URL string.
```

--------------------------------

### Usage syntax for litefs-bench

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/bench.md

Shows the command-line usage pattern: litefs-bench MODE [arguments] DSN.

```sh
litefs-bench MODE [arguments] DSN
```

--------------------------------

### PrimaryNode constants and constructor

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/fuse-nodes.md

Defines the filename `.primary` and the constructor for the PrimaryNode. The file lists the current primary hostname and is only present when the node knows a remote primary; otherwise `lookupPrimaryNode` returns `ENOENT`.

```go
// PrimaryFilename is the name of the file that holds the current primary.
const PrimaryFilename = ".primary"
func newPrimaryNode(fsys *FileSystem) *PrimaryNode
```

--------------------------------

### Shell commands to read replication state

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/fuse-nodes.md

Shows how to read the virtual files from the mount point: `cat /litefs/myapp-pos` for the replication position, `cat /litefs/.lag` for lag, and `cat /litefs/.primary` for the primary hostname.

```sh
# Current replication position (TXID + checksum):
cat /litefs/myapp-pos
# Lag behind primary, in seconds:
cat /litefs/.lag
# Hostname of the current primary (replicas only):
cat /litefs/.primary
```

--------------------------------

### internal package helper function signatures

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/internal.md

Declares the three helper functions in the internal package. Sync opens, fsyncs, and closes a path, typically used after atomic renames to fsync parent directories for crash safety. ReadFullAt fills a buffer from ReadAt, returning io.ErrUnexpectedEOF on partial reads and propagating EOF when n == 0. Close swallows nil closers and benign errors containing "use of closed network connection" or "http: Server closed".

```go
// Sync performs an fsync on the given path. Typically used for directories.
func Sync(path string) error

// ReadFullAt is an implementation of io.ReadFull() but for io.ReaderAt.
func ReadFullAt(r io.ReaderAt, buf []byte, off int64) (n int, err error)

// Close closes closer but ignores select errors.
func Close(closer io.Closer) (err error)
```

--------------------------------

### RunCommand struct and constructor

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/cli.md

Defines the RunCommand type with fields for promotion, candidate check, halt lock path, command, arguments, URL, and verbose logging. The constructor NewRunCommand returns a new instance.

```go
type RunCommand struct {
	Promote bool
	IfCandidate bool
	WithHaltLockOn string
	Cmd  string
	Args []string
	URL string
	Verbose bool
}

func NewRunCommand() *RunCommand
```

--------------------------------

### SyncBackup method signature

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/store.md

Performs a one-time sync to the backup service via streamBackup(ctx, true), used for deterministic testing. During primary operation, monitorPrimaryBackup continuously streams changes after BackupDelay.

```go
func (s *Store) SyncBackup(ctx context.Context) error
```

--------------------------------

### Entry point and command dispatch declarations

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/cli.md

Declares the version and commit variables, the DefaultURL constant, and the main entry point functions for the litefs CLI.

```go
var (
	Version = ""
	Commit  = ""
)

// DefaultURL refers to the LiteFS API on the local machine.
const DefaultURL = "http://localhost:20202"

func main()
func run(ctx context.Context, args []string) error
func VersionString() string
func printUsage()
```

--------------------------------

### Open

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/lfsc.md

Validates the client configuration, requiring an http or https scheme and a host.

```APIDOC
## Open

### Description
Validates the client configuration, requiring an http or https scheme and a host.

### Method
Open

### Signature
func (c *BackupClient) Open() (err error)

### Parameters
None

### Returns
- **err** (error) - Error if validation fails.

```

--------------------------------

### Client struct and NewClient function

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/http-client.md

Defines the HTTP client struct with an underlying http.Client and a constructor that returns a new Client instance.

```go
type Client struct {
	// Underlying HTTP client
	HTTPClient *http.Client
}

func NewClient() *Client
```

--------------------------------

### monitor and Usage function signatures

Source: https://github.com/superfly/litefs/blob/main/_autodocs/api-reference/bench.md

Signatures for monitor and Usage functions.

```go
func monitor(ctx context.Context)
func Usage()
```
Tokens:
Raw