sqlitestream

Open a SQLite database with WAL PRAGMAs suitable for Litestream. When a replica URL is set, the file is restored from the replica if it is missing locally, and continuous replication runs in the background until Close.

Pure-Go: uses the modernc.org/sqlite driver, no cgo.

Install

go get github.com/luzilla/sqlitestream

API

funcOpen(ctx context.Context, pathstring, opts...Option) (*DB, error)
funcRestore(ctx context.Context, outputPathstring, forcebool, opts...Option) errorfunc (*DB) DB() *sql.DB// underlying handlefunc (*DB) Close(ctx context.Context) error// flushes final WAL, stops replicationfuncWithReplicaURL(urlstring) OptionfuncWithAWSCredentials(accessKeyID, secretAccessKeystring) OptionfuncWithLogger(logger*slog.Logger) Option

Without WithReplicaURL, Open just opens the file in WAL mode and does no replication.

Replica URL

Tip

While litestream supports an umbrella of cloud storages, this library uses AWS S3 compatible object storage only. Contributions to enable other backends, are very welcome.

An S3 replica URL looks like:

s3://bucket/path?region=eu-central-1

For an S3-compatible endpoint add endpoint and forcePathStyle:

s3://bucket/path?endpoint=http://127.0.0.1:9000&region=eu-central-1&forcePathStyle=true

Important

Pass credentials with WithAWSCredentials. Without them, Litestream falls back to the AWS default chain (env vars, shared config, instance role). Credentials in the URL userinfo (s3://key:secret@…) are not read.

Examples

• examples/plain — database/sql
• examples/entgo — Ent

Documentation

Please see docs.

Development

make test# go test -race
make lint # go vet + go fmt

The suite includes an S3 round-trip test that starts an S3 mock server (adobe/s3mock); it needs a running Docker daemon.