Command: restore

The restore command recovers a database from a replica. By default, it attempts to restore the latest data. However, it can also restore databases to a specific point-in-time if it is covered by the WAL time range.

Restoration will only run if the output database file does not exist so you cannot accidentally overwrite your running database.


With a database path

This command will restore a database specified in the Litestream configuration file to its original location.

litestream restore [arguments] DB_PATH

With a replica URL

This command will restore from a replica without using the Litestream configuration file. It is useful if you don’t have a configuration file such as on a development machine.

litestream restore [arguments] REPLICA_URL


    Output path of the restored database.
    Defaults to original DB path.

    Returns exit code of 0 if the database already exists.

    Returns exit code of 0 if no backups found.

-parallelism NUM
    Determines the number of WAL files downloaded in parallel.
    Defaults to 8

    Verbose output.

-replica NAME
    Restore from a specific replica.
    Defaults to replica with latest data.

-generation NAME
    Restore from a specific generation.
    Defaults to generation with latest data.

-index NUM
    Restore up to a specific WAL index (inclusive).
    Defaults to use the highest available index.

-timestamp TIMESTAMP
    Restore to a specific point-in-time.
    Defaults to use the latest available backup.

-config PATH
    Specifies the configuration file.
    Defaults to /etc/litestream.yml

    Disables environment variable expansion in configuration file.


Database restore

Restore the latest replica for the /var/lib/db database to its original location:

$ litestream restore /var/lib/db

Replica URL restore

Restore from an S3 replica URL to /tmp/my.db:

$ litestream restore -o /tmp/my.db s3://

Restore to new path

Restores the /var/lib/db database to /tmp/db instead of its original location:

$ litestream restore -o /tmp/db /var/lib/db

Point-in-time restore

Restore the /var/lib/db database to a specific point-in-time:

$ litestream restore -timestamp 2020-01-01T00:00:00Z /var/lib/db

Filter by replica name

This example will only restore from the s3 replica:

$ litestream restore -replica s3 /var/lib/db