Litestream

https://litestream.io/
Admin
Litestream provides continuous backup and point-in-time recovery for SQLite databases by streaming...
Tokens:147,114
Snippets:1,472
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start replication example

Source: https://litestream.io/reference/start

Example of starting replication for a database. The command resumes replication and prints a confirmation with the current transaction ID and socket path.

```shell
$ litestream start /path/to/my.db
status: started
db_path: /path/to/my.db
state: running
txid: 42
socket: /var/run/litestream.sock

```

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

### Idempotent start example

Source: https://litestream.io/reference/start

Example of calling start on an already-running database. The command is idempotent and returns status 'already_running' with exit code 0.

```shell
$ litestream start /path/to/my.db
status: already_running
db_path: /path/to/my.db
state: running
txid: 42
socket: /var/run/litestream.sock

```

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

### litestream start

Source: https://litestream.io/reference/start

Documentation for the `litestream start` command, including usage, arguments, behavior, output fields, and examples.

```APIDOC
## [CLI] litestream start

### Description
Resumes replication for a database that was previously stopped via the `stop` command. The database must already be registered with the daemon.

### Usage
```
litestream start [arguments] DB_PATH
```

### Arguments
- `-socket PATH` - Path to the control socket. Defaults to `/var/run/litestream.sock`.
- `-timeout SECONDS` - Maximum time to wait in seconds. Defaults to `30`.
- `-json` - Output raw JSON instead of human-readable text.

### Behavior
The `start` command is **idempotent**. If the database is already running (replicating), the command returns `already_running` status and exits successfully (exit code 0). This allows scripts to safely call `start` without checking the current replication state.

### Output
By default, the command displays a human-readable confirmation:
```
status: started
db_path: /path/to/my.db
state: running
txid: 42
socket: /var/run/litestream.sock
```

With `-json`, the response is a JSON object:

| Field | Description |
|-------|-------------|
| `status` | Either `started` or `already_running` |
| `db_path` | Absolute path to the database file |
| `state` | Current state after command: `running` |
| `txid` | Current transaction ID |
| `socket` | Control socket path used |

### Examples

#### Start replication
```
$ litestream start /path/to/my.db
status: started
db_path: /path/to/my.db
state: running
txid: 42
socket: /var/run/litestream.sock
```

#### Idempotent start
Calling `start` on an already-running database succeeds:
```
$ litestream start /path/to/my.db
status: already_running
db_path: /path/to/my.db
state: running
txid: 42
socket: /var/run/litestream.sock
```

#### JSON output
```
$ litestream start -json /path/to/my.db
{
  "status": "started",
  "db_path": "/path/to/my.db",
  "state": "running",
  "txid": 42,
  "socket": "/var/run/litestream.sock"
}
```

#### Custom socket path
```
$ litestream start -socket /tmp/litestream.sock /path/to/my.db
```
```

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

### Install Litestream from source with go install

Source: https://litestream.io/install/source

Downloads the source code and installs the litestream binary into $GOPATH/bin. Requires the Go toolchain to be installed first.

```bash
go install ./cmd/litestream

```

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

### Example: Empty database list

Source: https://litestream.io/reference/list

Shows the output when no databases are configured: 'No databases configured'.

```bash
$ litestream list
No databases configured

```

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

### Install Litestream with Homebrew

Source: https://litestream.io/install/mac

Installs Litestream via Homebrew tap. Requires Homebrew to be installed first. Verify with `litestream version`.

```bash
brew install benbjohnson/litestream/litestream

```

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

### Configure Backblaze B2 replica in litestream.yml

Source: https://litestream.io/guides/backblaze

Use this YAML configuration in your litestream.yml file to set up a Backblaze B2 replica. The example assumes you have already created a bucket and copied its details into the appropriate fields. Change the path and endpoint values to match your setup.

```yaml
dbs:
  - path: path-to-your-local-db-file
    replica:
      type: s3
      bucket: your-bucket-name
      path: db # change to whatever path you want
      endpoint: s3.us-west-000.backblazeb2.com # change this
      force-path-style: true

```

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

### litestream start usage

Source: https://litestream.io/reference/start

Shows the command-line syntax for the start command. The DB_PATH argument is required and must reference a database already registered with the daemon.

```shell
litestream start [arguments] DB_PATH

```

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

### Install NATS CLI tool

Source: https://litestream.io/guides/nats

Installs the NATS CLI tool using either Go or curl. The curl method pipes the installation script to sh and then moves the binary to /usr/local/bin/.

```bash
# Using Go
go install github.com/nats-io/natscli/nats@latest

# Using curl
curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh
sudo mv nats /usr/local/bin/

```

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

### Start Litestream and Monitor Sync

Source: https://litestream.io/docs/migration

Start Litestream and wait for the replica to catch up. Follow the journal to monitor sync progress.

```bash
sudo systemctl start litestream
journalctl -u litestream -f
```

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

### Install Litestream .deb package with dpkg

Source: https://litestream.io/install/linux

Installs the downloaded Debian package. After this, run `litestream version` to verify the installation.

```bash
sudo dpkg -i litestream-0.5.14-linux-x86_64.deb

```

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

### Backup Litestream Setup

Source: https://litestream.io/docs/migration

Backs up the current Litestream setup before upgrading to v0.5.0+. Stops the service, copies the configuration file, and backs up the binary.

```bash
# Stop Litestream
sudo systemctl stop litestream

# Backup configuration
cp /etc/litestream.yml /etc/litestream.yml.backup

# Backup binary
cp $(which litestream) /usr/local/bin/litestream.backup
```

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

### Unregister a database example

Source: https://litestream.io/reference/unregister

Example command and output for unregistering a database, showing the human-readable confirmation.

```bash
$ litestream unregister /path/to/my.db
status: unregistered
db_path: /path/to/my.db
final_txid: 42
socket: /var/run/litestream.sock

```

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

### Custom timeout example

Source: https://litestream.io/reference/unregister

Example of using -timeout to wait up to 60 seconds for the final sync to complete.

```bash
$ litestream unregister -timeout 60 /path/to/my.db

```

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

### litestream_info Example Output

Source: https://litestream.io/reference/mcp

Example output from the litestream_info tool. Shows version, config path, databases, and LTX files.

```text
=== Litestream Status Report ===

Version Information:
0.5.14

Current Config Path:
/etc/litestream.yml

Databases:
path               replica
/var/lib/myapp.db  s3

LTX Files:
Database: /var/lib/myapp.db
level  min_txid          max_txid          size  created
0      0000000000000001  0000000000000001  657   2025-01-15T10:00:00Z
0      0000000000000002  0000000000000002  209   2025-01-15T10:15:00Z

```

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

### litestream_ltx Example Output

Source: https://litestream.io/reference/mcp

Example output from the litestream_ltx tool. Lists available LTX files for a database or replica.

```text
level  min_txid          max_txid          size  created
0      0000000000000001  0000000000000001  657   2025-01-15T10:00:00Z
0      0000000000000002  0000000000000002  209   2025-01-15T10:15:00Z
0      0000000000000003  0000000000000003  663   2025-01-15T10:30:00Z

```

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

### litestream_version Example Output

Source: https://litestream.io/reference/mcp

Example output from the litestream_version tool. Prints the Litestream version.

```text
0.5.14

```

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

### litestream_databases Example Output

Source: https://litestream.io/reference/mcp

Example output from the litestream_databases tool. Lists configured databases and their replica types.

```text
path               replica
/var/lib/myapp.db  s3
/var/lib/other.db  file

```

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

### Custom socket path example

Source: https://litestream.io/reference/info

Example of using the `-socket` argument to specify a custom control socket path. The default path is `/var/run/litestream.sock`.

```bash
$ litestream info -socket /tmp/litestream.sock

```

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

### Dry run example

Source: https://litestream.io/reference/unregister

Example of using -dry-run to preview what would be unregistered without making changes, showing the preview output and that no request is sent.

```bash
$ litestream unregister -dry-run /path/to/my.db
Dry run: unregister request preview
  database: /path/to/my.db
  socket: /var/run/litestream.sock
  replicas: daemon-managed replica for this database
  final sync: daemon close will sync the database and replica before the command completes
  timeout: 30s
No unregister request was sent.

```

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

### Example retention timing configuration: interval=30m + retention=1h

Source: https://litestream.io/docs/troubleshooting

Shows the timing example used to illustrate when snapshots become eligible for deletion. The configuration uses interval=30m and retention=1h, with the first snapshot created at T+30m and the second at T+1h. The first snapshot becomes eligible for deletion at T+1h30m, so minimum 1.5 hours pass before L1+ cleanup begins.

```text
Configuration: `interval=30m` + `retention=1h` (the defaults are `24h`/`24h`)
First snapshot created at T+30m (age: 0)
Second snapshot created at T+1h (first snapshot age: 30m)
First snapshot becomes eligible for deletion at T+1h30m (age exceeds 1h)
Result: Minimum 1.5 hours before L1+ cleanup begins
```

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

### Load Litestream VFS in SQLite CLI

Source: https://litestream.io/guides/vfs

Load the Litestream VFS as a loadable extension in the SQLite CLI. Requires setting AWS credentials and the replica URL before starting sqlite3. The macOS system SQLite has extension loading disabled; install SQLite via Homebrew (`brew install sqlite3`) or use the Python example instead.

```bash
# Set credentials (for AWS S3)
export AWS_ACCESS_KEY_ID=AKIAxxxx
export AWS_SECRET_ACCESS_KEY=xxxx

# Set replica URL
export LITESTREAM_REPLICA_URL="s3://my-backups/prod.db"

sqlite3
sqlite> .load ./dist/litestream-vfs sqlite3_litestreamvfs_init
sqlite> .open 'file:prod.db?vfs=litestream'
sqlite> SELECT count(*) FROM users LIMIT 10;

```

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

### List all databases example

Source: https://litestream.io/reference/databases

Shows a single database `/var/lib/db` defined in the configuration file with a `file` replica. The command prints a table with columns `path` and `replica`.

```shell
$ litestream databases
path         replica
/var/lib/db  file

```

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

### Example Get-EventLog output for Litestream

Source: https://litestream.io/guides/windows

Example output from Get-EventLog showing Litestream service events in reverse chronological order, including replication, initialization, version, and service start messages.

```text
PS C:\> Get-EventLog -LogName Application -Source Litestream

   Index Time          EntryType   Source                 InstanceID Message
   ----- ----          ---------   ------                 ---------- -------
    8894 Jan 01 00:00  Information Litestream                      1 replicating to: name="s3" type="s3" bucket="dev...
    8892 Jan 01 00:00  Information Litestream                      1 initialized db: C:\my.db...
    8891 Jan 01 00:00  Information Litestream                      1 litestream v0.5.14...
    8890 Jan 01 00:00  Information Litestream                      1 Litestream service starting...
```

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

### JSON output example

Source: https://litestream.io/reference/start

Example of using the -json flag to get raw JSON output. The response includes the status, absolute database path, current state, transaction ID, and control socket path.

```shell
$ litestream start -json /path/to/my.db
{
  "status": "started",
  "db_path": "/path/to/my.db",
  "state": "running",
  "txid": 42,
  "socket": "/var/run/litestream.sock"
}

```

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

### Build commands for v0.3.x vs v0.5.0+

Source: https://litestream.io/docs/migration

v0.5.0+ simplifies the build process by removing the cgo requirement for the main binary. Use `CGO_ENABLED=0` or omit it entirely for v0.5.0+.

```bash
# v0.3.x required cgo
CGO_ENABLED=1 go build ./cmd/litestream

# v0.5.0+ does not require cgo for main binary
CGO_ENABLED=0 go build ./cmd/litestream
```

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

### Basic daemon info output

Source: https://litestream.io/reference/info

Example of the default human-readable output from the info command. It displays the Litestream version, process ID, uptime, start time, and the number of databases managed.

```bash
$ litestream info
Litestream 0.5.12
  PID:        12345
  Uptime:     1h30m0s
  Started at: 2026-05-28T10:00:00Z
  Databases:  3

```

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

### Go: Configure S3 client and register VFS

Source: https://litestream.io/guides/vfs-write-mode

Go example that configures an S3 replica client, creates a Litestream VFS with write mode enabled, and registers it with sqlite3vfs. It then opens a SQLite database using the 'litestream' VFS and performs basic operations.

```go
package main

import (
    "context"
    "database/sql"
    "log"
    "os"
    "time"

    _ "github.com/mattn/go-sqlite3"
    "github.com/psanford/sqlite3vfs"

    "github.com/benbjohnson/litestream"
    "github.com/benbjohnson/litestream/s3"
)

func main() {
    client := s3.NewReplicaClient()
    client.AccessKeyID = os.Getenv("AWS_ACCESS_KEY_ID")
    client.SecretAccessKey = os.Getenv("AWS_SECRET_ACCESS_KEY")
    client.Region = "us-east-1"
    client.Bucket = "mybucket"
    client.Path = "app.db"
    if err := client.Init(context.Background()); err != nil {
        log.Fatal(err)
    }

    vfs := litestream.NewVFS(client, nil)
    vfs.WriteEnabled = true
    vfs.WriteSyncInterval = 1 * time.Second
    vfs.WriteBufferPath = "/tmp/litestream-buffer.db"

    if err := sqlite3vfs.RegisterVFS("litestream", vfs); err != nil {
        log.Fatal(err)
    }

    db, err := sql.Open("sqlite3", "file:app.db?vfs=litestream")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // Create table and insert data
    db.Exec("CREATE TABLE IF NOT EXISTS events (id INTEGER PRIMARY KEY, ts TEXT)")
    db.Exec("INSERT INTO events (ts) VALUES (datetime('now'))")

    // Query
    rows, _ := db.Query("SELECT * FROM events")
    defer rows.Close()
    for rows.Next() {
        var id int
        var ts string
        rows.Scan(&id, &ts)
        log.Printf("Event %d: %s", id, ts)
    }
}

```

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

### Example output: litestream list

Source: https://litestream.io/reference/list

Shows the default human-readable output format with database paths, status, and last sync time.

```bash
$ litestream list
/var/lib/app.db [replicating] (last sync: 2026-05-28T10:30:00Z)
/var/lib/users.db [replicating] (last sync: 2026-05-28T10:29:45Z)

```

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

### Install Litestream v0.5.14

Source: https://litestream.io/docs/migration

Downloads and installs Litestream v0.5.14 for Linux x86_64. Verifies the installation with `litestream version`.

```bash
# Download latest stable release (check https://github.com/benbjohnson/litestream/releases)
wget https://github.com/benbjohnson/litestream/releases/download/v0.5.14/litestream-0.5.14-linux-x86_64.tar.gz

# Extract and install
tar -xzf litestream-0.5.14-linux-x86_64.tar.gz
sudo mv litestream /usr/local/bin/
sudo chmod +x /usr/local/bin/litestream

# Verify installation
litestream version
```

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

### Run-once mode example

Source: https://litestream.io/reference/replicate

Performs a single sync of all databases and replicas, then exits. Useful for cron jobs, CI/CD pipelines, and backup scripts. Cannot be combined with `-exec`.

```bash
litestream replicate -once /var/lib/mydb.db s3://mybucket/mydb

```

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

### Initialize New Replica with Existing Data

Source: https://litestream.io/docs/migration

Initialize a new replica with existing data by stopping replication, updating the configuration to the new replica type, and starting replication to sync the current database.

```bash
# Stop replication
sudo systemctl stop litestream

# Update configuration to new replica type
# Start replication (will sync current database)
sudo systemctl start litestream
```

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

### litestream start default output

Source: https://litestream.io/reference/start

Shows the default human-readable output of the start command. The status field is either 'started' or 'already_running', and the state is always 'running' after the command.

```shell
status: started
db_path: /path/to/my.db
state: running
txid: 42
socket: /var/run/litestream.sock

```

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

### Run replicate in command-line mode

Source: https://litestream.io/reference/replicate

Sets up replication for a single database file to a single replica URL without a configuration file. Multiple replicas per database are not supported in command-line mode; credentials must be passed via environment variables.

```bash
litestream replicate [arguments] DB_PATH REPLICA_URL

```

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

### Example: Custom socket path

Source: https://litestream.io/reference/list

Shows how to specify a custom control socket path using the `-socket` flag.

```bash
$ litestream list -socket /tmp/litestream.sock

```

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

### Perform initial sync after switching to S3 replica

Source: https://litestream.io/docs/migration

Stop the current replication, start with the new configuration, and verify replication. Run these commands after updating the configuration file.

```bash
# Stop current replication
sudo systemctl stop litestream

# Start with new configuration
sudo systemctl start litestream

# Verify replication
litestream databases

```

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

### Run replicate with configuration file

Source: https://litestream.io/reference/replicate

Starts the Litestream daemon using a configuration file. This is the recommended approach for production systems.

```bash
litestream replicate [arguments]

```

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

### Configure DigitalOcean Spaces replica with URL format

Source: https://litestream.io/guides/digitalocean

Configuration file example using the url format to define a replica. Includes access key credentials and the replica URL.

```yaml
access-key-id: xxxxxxxxxxxxxxxxxxxx
secret-access-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxx

dbs:
  - path: /path/to/local/db
    replica:
      url: s3://SPACENAME.nyc3.digitaloceanspaces.com/db

```

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

### litestream_restore Example Input

Source: https://litestream.io/reference/mcp

Example JSON input for the litestream_restore tool to restore to a specific timestamp.

```json
{
  "path": "/var/lib/myapp.db",
  "o": "/tmp/restored.db",
  "timestamp": "2025-01-15T10:00:00Z"
}

```

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

### litestream_status Example Output

Source: https://litestream.io/reference/mcp

Example output from the litestream_status tool. Shows replication health for each database.

```text
database           status  local txid        wal size
/var/lib/myapp.db  ok      0000000000000005  21 kB
/var/lib/other.db  ok      0000000000000003  4.1 kB

```

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

### Replicate database to SFTP using command line

Source: https://litestream.io/guides/sftp

Use this command to start replication to an SFTP server. Replace placeholders with your username, password, server, and path. The port is optional if using default SSH port 22.

```bash
litestream replicate /path/to/db sftp://USER:PASSWORD@HOST:PORT/PATH

```

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

### JSON output example

Source: https://litestream.io/reference/unregister

Example of using -json to output raw JSON instead of human-readable text.

```bash
$ litestream unregister -json /path/to/my.db
{
  "status": "unregistered",
  "db_path": "/path/to/my.db",
  "final_txid": 42,
  "socket": "/var/run/litestream.sock"
}

```

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

### Configure replica with expanded fields

Source: https://litestream.io/guides/s3

Configuration file example using separate fields for type, bucket, path, and optional region.

```yaml
dbs:
  - path: /path/to/local/db
    replica:
      type: s3
      bucket: BUCKETNAME
      path:   PATHNAME
      region: us-east-1   # optional, set to your region

```

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

### POST /sync fire-and-forget example

Source: https://litestream.io/reference/ipc

Forces an immediate WAL-to-LTX sync for a database. Without `wait`, the sync is triggered and the request returns immediately (fire-and-forget). The response shows local sync status with the current and replicated transaction IDs.

```bash
$ curl --unix-socket /var/run/litestream.sock \
    -X POST http://localhost/sync \
    -H "Content-Type: application/json" \
    -d '{"path":"/path/to/my.db"}'
{"status":"synced_local","path":"/path/to/my.db","txid":42,"replicated_txid":40}
```

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

### Install Litestream RPM with dnf

Source: https://litestream.io/install/linux

Installs the downloaded .rpm package using dnf (or yum on older systems).

```bash
sudo dnf install litestream-0.5.14-linux-x86_64.rpm

```

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

### Database-level options with meta-path (YAML)

Source: https://litestream.io/reference/config

Example with database-level options including `meta-path`, `monitor-interval`, `checkpoint-interval`, `busy-timeout`, `min-checkpoint-page-count`, `truncate-page-n`, and replica `sync-interval`. Note that `meta-path` cannot be combined with `meta-dir`.

```yaml
dbs:
  - path: /var/lib/myapp.db
    meta-path: /var/lib/myapp-litestream
    monitor-interval: 500ms
    checkpoint-interval: 30s
    busy-timeout: 5s
    min-checkpoint-page-count: 500
    truncate-page-n: 50000  # ~200MB emergency truncation
    replica:
      url: s3://mybucket/myapp
      sync-interval: 1s

```

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

### Create S3 bucket and configure credentials

Source: https://litestream.io/docs/migration

Creates an S3 bucket and configures AWS credentials before migrating a Litestream replica from file storage to S3.

```bash
# Create S3 bucket
aws s3 mb s3://my-litestream-backups

# Configure credentials
aws configure

```

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

### Run Litestream with a replica URL using environment variables

Source: https://litestream.io/guides/docker

For basic replication of a single database, set S3 credentials via environment variables, mount a volume to read from, and specify the path and replica as arguments.

```bash
docker run \
  --env LITESTREAM_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID \
  --env LITESTREAM_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY \
  -v /local/path/to/data:/data \
  litestream/litestream replicate s3://BUCKET/db

```

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

### Start NATS server with JetStream enabled

Source: https://litestream.io/docs/migration

Starts a NATS server with JetStream enabled for use as a Litestream replica target.

```bash
# Start NATS with JetStream enabled
nats-server -js

```

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

### Idempotent unregistration example

Source: https://litestream.io/reference/unregister

Example of calling unregister on an already-unregistered database, showing the 'already_unregistered' status and exit code 0.

```bash
$ litestream unregister /path/to/my.db
status: already_unregistered
db_path: /path/to/my.db
final_txid: 0
socket: /var/run/litestream.sock

```

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

### Select SQLite driver for library users

Source: https://litestream.io/docs/migration

For library users, choose between the pure Go driver (default) and the cgo-based driver for VFS support or experimental features. Uncomment the cgo driver to use it.

```go
import (
    // Pure Go driver (default in v0.5.0+)
    _ "modernc.org/sqlite"

    // OR cgo-based driver (for VFS/experimental features)
    // _ "github.com/mattn/go-sqlite3"
)
```
Tokens:
Raw