litestream

Litestream
![GitHub release (latest by date)](https://img.shields.io/github/v/release/benbjohnson/litestream)
![Status](https://img.shields.io/badge/status-beta-blue)
![GitHub](https://img.shields.io/github/license/benbjohnson/litestream)
[![Docker Pulls](https://img.shields.io/docker/pulls/litestream/litestream.svg?maxAge=604800)](https://hub.docker.com/r/litestream/litestream/)
==========

Litestream is a standalone disaster recovery tool for SQLite. It runs as a
background process and safely replicates changes incrementally to another file
or S3. Litestream only communicates with SQLite through the SQLite API so it
will not corrupt your database.

If you need support or have ideas for improving Litestream, please visit
[GitHub Issues](https://github.com/benbjohnson/litestream/issues).
Please visit the [Litestream web site](https://litestream.io) for installation
instructions and documentation.

For optional service confinement, see the [systemd hardening guide](docs/SYSTEMD.md).

If you find this project interesting, please consider starring the project on
GitHub.

File replica URLs
-----------------

File replica URLs use URL path escaping. For example,
`file:///backups/daily%20backup` refers to `/backups/daily backup`. Unicode paths
are supported as well. Encode a literal percent sign as `%25`: a directory
named `/backups/daily%20backup` is addressed by
`file:///backups/daily%2520backup`.

Earlier versions wrote file replicas to the escaped form of the path, such as
`/backups/daily%20backup`. If that directory exists and the decoded path does
not, Litestream keeps using it and logs a warning with the command to rename
it. If both directories exist, Litestream returns an error until one is merged
or removed.

Source database changes
-----------------------

When Litestream begins replicating a database, it creates an internal
`_litestream_lock` table in the source SQLite database. This is expected and
safe to leave in place. Litestream uses the table to acquire SQLite's write
lock while coordinating synchronization around WAL checkpoints. The writes
occur in transactions that are rolled back, so Litestream does not leave rows
in the table.

The table is part of the source database, not a separate table in the replica
destination. Because the source schema is backed up, restored databases also
contain it. Its creation changes the source database schema and can change its
page count or bytes, so a database under Litestream should not be expected to
remain byte-identical to its pre-Litestream state.

Do not drop `_litestream_lock` while Litestream is running. Synchronization
around a checkpoint can fail until Litestream reinitializes the database.
Restarting Litestream recreates the missing table automatically.

Stopping replication
--------------------

`litestream replicate` attempts a graceful shutdown on SIGINT or SIGTERM.
The top-level `shutdown-timeout` configuration setting limits the entire shutdown,
including waiting for startup, an `ex