Configuration File
The YAML configuration file provides a way to list databases and replicas that Litestream should manage. In addition, there are global variables that can be applied to all replicas.
The default path for the configuration file is /etc/litestream.yml
.
Variable expansion
By default, Litestream will perform environment variable expansion within the
config file before reading it. Any references to $VAR
or ${VAR}
formatted
variables will be replaced with their environment variable values. If no value
is set then it will be replaced with an empty string.
This can cause issues if you have a value in a configuration file which has a
dollar sign followed by characters—for example, a password. In this case, you
can set the -no-expand-env
flag on any litestream
command to disable
expansion.
Global settings
AWS credentials
If you are using AWS S3 replication, it can be useful to specify your credentials in one place instead of for each replica:
access-key-id: AKIAxxxxxxxxxxxxxxxx
secret-access-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxx
Metrics
Litestream produces a continuous stream of metrics that are exported as a Prometheus endpoint. These are disabled by default as it requires an HTTP server to start. You can enable it by setting a bind address in the config:
addr: ":9090"
When you start Litestream with this setting enabled, you’ll see metrics at http://localhost:9090/metrics
MCP (Model Context Protocol)
v0.5.0 Litestream includes built-in support for the Model Context Protocol (MCP), allowing AI assistants to interact with your databases and replicas. Enable the MCP server by setting a bind address:
mcp-addr: ":3001"
When enabled, the MCP server will start alongside replication and provide AI tools at http://localhost:3001. See the MCP command reference for available tools and usage.
Logging
v0.3.12
Log type
can be set to either “text” or “json”.
Logging level
can be set to “debug”, “info”, “warn” or “error”. By setting
stderr
to true
logs will be written to stderr instead of stdout.
The defaults are shown below:
logging:
level: info
type: text
stderr: false
Database settings
Litestream can monitor one or more database files that are specified in the
configuration file. Database files are also referenced in litestream
commands
by their absolute path.
Each database configuration includes the database path and replica configuration.
v0.5.0
Database configuration has been simplified to use a single
replica
field instead of the deprecated replicas
array.
dbs:
- path: /var/lib/db1
replica:
url: s3://mybkt.litestream.io/db1
- path: /var/lib/db2
replica:
url: nats://nats.example.com:4222/my-bucket
username: litestream
password: ${NATS_PASSWORD}
Database configuration options
Each database supports the following configuration options:
path
—Absolute path to the SQLite database filemeta-path
—Path to store Litestream metadata (defaults to<path>-litestream
)monitor-interval
—How often to check for changes (default:1s
)checkpoint-interval
—How often to perform WAL checkpoints (default:1m
)busy-timeout
—SQLite busy timeout (default:1s
)min-checkpoint-page-count
—Minimum pages before checkpointing (default:1000
)max-checkpoint-page-count
—Maximum pages before forcing checkpoint (default:10000
)replica
—Single replica configuration (replaces deprecatedreplicas
array)
Example with database-level options:
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
max-checkpoint-page-count: 5000
replica:
url: s3://mybucket/myapp
sync-interval: 1s
Replica settings
Litestream supports six types of replicas:
"abs"
replicates a database to an Azure Blob Storage container."file"
replicates a database to another local file path."gs"
replicates a database to a Google Cloud Storage bucket."nats"
replicates a database to a NATS JetStream Object Store."s3"
replicates a database to an S3-compatible bucket."sftp"
replicates a database to a remote server via SFTP.
All replicas have unique name which is specified by the "name"
field. If a
name is not specified then the name defaults to the replica type. The name is
only needed when using multiple replicas of the same type on a database.
The following replica settings are also available for all replica types:
-
url
—Short-hand form of specifying a replica location. Setting this field will apply changes to multiples fields includingbucket
,path
,region
, etc. -
retention
—The amount of time that snapshot & LTX files will be kept. After the retention period, a new snapshot will be created and the old one will be removed. LTX files that exist before the oldest snapshot will also be removed. Defaults to24h
. -
retention-check-interval
—Specifies how often Litestream will check if retention needs to be enforced. Defaults to1h
. -
snapshot-interval
—Specifies how often new snapshots will be created. This is used to reduce the time to restore since newer snapshots will have fewer LTX frames to apply. Retention still applies to these snapshots.If you do not set a snapshot interval then a new snapshot will be created whenever retention is performed. Retention occurs every 24 hours by default.
-
validation-interval
—When specified, Litestream will automatically restore and validate that the data on the replica matches the local copy. Disabled by default. Enabling this will significantly increase the cost of running Litestream as S3 services charge for downloads. -
sync-interval
—Frequency in which frames are pushed to the replica. Defaults to1s
. Increasing frequency can increase cloud storage costs significantly. -
age
—Client-side encryption with age, see Encryption for configuration details. Defaults to off.
S3 replica
The easiest way to configure an S3 replica is to use the url
field:
dbs:
- path: /var/lib/db
replicas:
- url: s3://mybkt.litestream.io/db
However, you can break this out into separate fields as well:
dbs:
- path: /var/lib/db
replicas:
- type: s3
bucket: mybkt.litestream.io
path: db
In addition, you can specify the region and AWS credentials per-replica:
dbs:
- path: /var/lib/db
replicas:
- url: s3://mybkt.litestream.io/db
region: us-east-1
access-key-id: AKIAxxxxxxxxxxxxxxxx
secret-access-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxx
The following settings are specific to S3 replicas:
-
access-key-id
—Replica-specific authentication key. If not specified, the global key or theLITESTREAM_ACCESS_KEY_ID
environment variable will be used instead. TheAWS_ACCESS_KEY_ID
variable can also be used. -
secret-access-key
—Replica-specific secret key. If not specified, the global secret or theLITESTREAM_SECRET_ACCESS_KEY
environment variable will be used instead. TheAWS_SECRET_ACCESS_KEY
variable can also be used. -
bucket
—Specifies the name of the remote bucket to replicate to. -
path
—Specifies the path to use within the bucket. -
region
—Specifies the bucket’s region. Only used for AWS S3 & Backblaze B2. -
endpoint
—Specifies the endpoint URL of the S3-compatible service. Only required for non-AWS services. -
force-path-style
—Uses the path style which is required by non-AWS services. This is automatically enabled ifendpoint
is set. -
skip-verify
—Disables TLS verification. This is useful when testing against a local node such as MinIO and you are using self-signed certificates.
File replica
File replicas can be configured using the "path"
field:
dbs:
- path: /var/lib/db
replicas:
- path: /backup/db
If no "type"
field is specified and a "url"
is not used then "file"
is
assumed.
Google Cloud Storage (GCS) replica
GCS replicas can be configured using the url
field:
dbs:
- path: /var/lib/db
replica:
url: gs://mybucket.example.com/db
Or by specifying individual fields:
dbs:
- path: /var/lib/db
replica:
type: gs
bucket: mybucket.example.com
path: db
GCS authentication uses Google Application Default Credentials (ADC). Set the
GOOGLE_APPLICATION_CREDENTIALS
environment variable to point to your service
account key file, or use workload identity in GKE environments.
Azure Blob Storage (ABS) replica
v0.5.0 Updated to use Azure SDK v2.
ABS replicas can be configured using the url
field:
dbs:
- path: /var/lib/db
replica:
url: abs://account@myaccount.blob.core.windows.net/container/db
Or by specifying individual fields:
dbs:
- path: /var/lib/db
replica:
type: abs
account-name: myaccount
account-key: ${AZURE_ACCOUNT_KEY}
bucket: container
path: db
endpoint: https://myaccount.blob.core.windows.net/
The following settings are specific to ABS replicas:
account-name
—Azure storage account nameaccount-key
—Azure storage account key or useAZURE_STORAGE_KEY
environment variablebucket
—Container name within the storage accountpath
—Path within the containerendpoint
—Custom endpoint URL (optional)
SFTP replica
SFTP replicas allow replication to remote servers via SSH File Transfer Protocol:
dbs:
- path: /var/lib/db
replica:
url: sftp://user:password@example.com:22/backup/db
Or with individual fields:
dbs:
- path: /var/lib/db
replica:
type: sftp
host: example.com:22
user: backup-user
password: ${SFTP_PASSWORD}
key-path: /etc/litestream/sftp_key
path: /backup/db
The following settings are specific to SFTP replicas:
host
—SFTP server hostname and portuser
—Username for authenticationpassword
—Password for authentication (not recommended for production)key-path
—Path to SSH private key file for key-based authenticationpath
—Remote path where replica files will be stored
NATS JetStream Object Store replica
v0.5.0 NATS JetStream Object Store provides distributed storage.
NATS replicas can be configured using the url
field:
dbs:
- path: /var/lib/db
replica:
url: nats://nats.example.com:4222/my-bucket
username: litestream
password: ${NATS_PASSWORD}
Or with individual fields:
dbs:
- path: /var/lib/db
replica:
type: nats
bucket: my-bucket
username: litestream
password: ${NATS_PASSWORD}
# TLS configuration
tls: true
root-cas:
- /etc/ssl/certs/nats-ca.crt
client-cert: /etc/ssl/certs/nats-client.crt
client-key: /etc/ssl/private/nats-client.key
# Connection tuning
max-reconnects: -1
reconnect-wait: 2s
timeout: 10s
The following settings are specific to NATS replicas:
Connection Settings:
bucket
—NATS JetStream Object Store bucket name (must be pre-created)max-reconnects
—Maximum reconnection attempts (-1 for unlimited)reconnect-wait
—Wait time between reconnection attemptstimeout
—Connection timeout
Authentication Options (choose one):
username
&password
—Basic username/password authenticationjwt
&seed
—JWT token and seed for NATS 2.0 authenticationcreds
—Path to NATS credentials filenkey
—NKey for signature-based authenticationtoken
—Simple token authentication
TLS Options:
tls
—Enable TLS encryptionroot-cas
—List of CA certificate file pathsclient-cert
—Client certificate for mutual TLSclient-key
—Client private key for mutual TLS
See the NATS Integration Guide for detailed setup instructions.
Legacy Multiple Replicas
Previous versions supported multiple replicas per database using the replicas
array.
This has been simplified to use a single replica
field:
Deprecated (v0.3.x and earlier):
dbs:
- path: /local/path/to/db
replicas:
- name: my_aws_replica
url: s3://myawsbucket/db
- name: my_do_replica
url: s3://mybkt.nyc3.digitaloceanspaces.com/db
Current (v0.5.0+):
dbs:
- path: /local/path/to/db
replica:
url: s3://myawsbucket/db
If you need multiple backup destinations, consider using your cloud provider’s cross-region replication features or multiple Litestream instances.
Retention period
Replicas maintain a snapshot of the database as well as a contiguous sequence of SQLite WAL page updates. These updates take up space so new snapshots are created and old WAL files are dropped through a process called “retention”.
The default retention period is 24h
. You can change that with the retention
field. Retention is enforced periodically and defaults to every 1h
. This can
be changed with the retention-check-interval
field.
dbs:
- path: /var/lib/db
replicas:
- url: s3://mybkt.litestream.io/db
retention: 4h
Duration values can be specified using second (s
), minute (m
), or hour (h
)
but days, weeks, & years are not supported.
Validation interval
Because Litestream performs physical replication, the resulting database files restored from replicas will match byte-for-byte. Litestream has an option to periodically validate replicas by restoring them and comparing their checksum to the primary database’s checksum.
Please note that frequently restoring from S3 can be expensive.
It can be enabled by setting the validation-interval
field:
dbs:
- path: /var/lib/db
replicas:
- url: s3://mybkt.litestream.io/db
validation-interval: 6h
Encryption
v0.3.10
Client-side encryption can be enabled per replica by adding an age
section to
the replica configuration with corresponding identities
and recipients
fields.
dbs:
- path: /var/lib/db
replica:
url: s3://mybkt.litestream.io/db
age:
identities:
- AGE-SECRET-KEY-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
recipients:
- age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
To generate keys, refer to the age README how to install and use the command line tools.
As of now identities must be a superset of recipients but key rotation can be achieved by adding a new identity while changing the recipient list to only have a key for it.
Note that enabling encryption after replication has already been done can confuse Litestream so it is recommended the replica is empty when doing so. Restoring from a replica that has mixed encrypted and non-encrypted files will fail.
Identity Files
v0.5.0 You can also reference identity files instead of embedding keys directly:
dbs:
- path: /var/lib/db
replica:
url: s3://mybkt.litestream.io/db
age:
identities:
- /etc/litestream/age-identity.txt
recipients:
- age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Complete Configuration Example
Example showing available configuration options:
# Global settings
access-key-id: ${AWS_ACCESS_KEY_ID}
secret-access-key: ${AWS_SECRET_ACCESS_KEY}
# Metrics endpoint
addr: ":9090"
# MCP server for AI integration
mcp-addr: ":3001"
# Subcommand to execute
exec: "myapp -config /etc/myapp.conf"
# Logging configuration
logging:
level: info
type: text
stderr: false
# Compaction levels
levels:
- interval: 5m
- interval: 1h
- interval: 24h
# Global snapshot settings
snapshot:
interval: 1h
retention: 24h
# Database configurations
dbs:
# S3 replica with encryption
- path: /var/lib/app1.db
monitor-interval: 1s
checkpoint-interval: 1m
replica:
url: s3://mybucket/app1
region: us-east-1
sync-interval: 1s
retention: 72h
age:
identities:
- /etc/litestream/age-identity.txt
recipients:
- age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# NATS replica with TLS
- path: /var/lib/app2.db
replica:
type: nats
url: nats://nats.example.com:4222/app2-bucket
username: litestream
password: ${NATS_PASSWORD}
tls: true
root-cas:
- /etc/ssl/certs/nats-ca.crt
max-reconnects: -1
reconnect-wait: 2s
# File replica for local backup
- path: /var/lib/app3.db
replica:
path: /backup/app3
retention: 168h # 1 week
Migration from v0.3.x
If you’re upgrading from Litestream v0.3.x, note these breaking changes:
- Multiple replicas deprecated: Use single
replica
field instead ofreplicas
array - LTX terminology: References to “WAL” are now “LTX” (Litestream Transaction Log)
- Updated cloud clients: AWS SDK v2, Azure SDK v2 with potential authentication changes
- New replica types: NATS and SFTP support added
- MCP integration: New AI assistant capabilities
See the Migration Guide for detailed upgrade instructions.