README

Litestream is a streaming replication tool for SQLite.

Introduction

This package is built for SQLite-first Laravel apps and will continuously stream SQLite changes to your preferred cloud storage or local files.

This will help you to quickly recover to the point of failure if your server goes down.

Litestream itself runs as a separate process and does not require application-level replication code changes. If you are new to Litestream, start with the official Litestream Getting Started guide and How it works.

Requirements

PHP ^8.4
Litestream binary support on macOS or Linux
SQLite should be configured correctly. (See Get Started)

Windows is not supported.

Installation

Install the package with Composer:

composer require eznix86/laravel-litestream

Publish the configuration file:

php artisan vendor:publish --tag=litestream-config

Get Started

Use this quick sequence to get replication running in a Laravel app.

1) Configure SQLite for Litestream safety

In config/database.php, make sure the target SQLite connection uses:

driver => sqlite
busy_timeout => 5000 (can be more but not less)
journal_mode => WAL
synchronous => NORMAL
foreign_key_constraints => true

2) Configure your Litestream replica

Update config/litestream.php:

set one or more connections
point each connection to one or more replica
configure the replica details under replicas (for example s3)

If you are using S3-compatible storage, review Litestream's official docs for provider-specific endpoint and credential requirements:

3) Install Litestream binary

php artisan litestream:install

This downloads the latest compatible Litestream binary to litestream.binary_path and marks it executable.

4) Start replication

php artisan litestream:replicate

The command validates configuration, regenerates YAML at litestream.config_path, and starts litestream replicate.

5) Verify status and test restore

php artisan litestream:status
php artisan litestream:reset
php artisan litestream:restore

For deeper operational guidance, see:

Replicas

Each replicas.<key> entry is passed through to Litestream YAML.

Keys are normalized recursively from snake_case to kebab-case when YAML is generated.
You can use ['env' => 'VAR_NAME'] for any replica value to emit ${VAR_NAME} in YAML and inject the real value at runtime via process environment.

For the complete list of replica options per backend, refer to the official Litestream configuration reference:

Replica settings reference

Example:

'replicas' => [
    's3' => [
        'type' => 's3',
        'bucket' => env('LITESTREAM_S3_BUCKET'),
        'path' => env('LITESTREAM_S3_PATH'),
        'access_key_id' => env('LITESTREAM_ACCESS_KEY_ID'),
        'secret_access_key' => env('LITESTREAM_SECRET_ACCESS_KEY'),
        'custom_options' => [
            'force_path_style' => true,
        ],
    ],
],

Generated YAML keys become:

access-key-id
secret-access-key
custom-options.force-path-style

Path Modes

path_mode controls how the replica path value is transformed per connection:

append: <replica.path>/<effective_connection_name>
replace: <effective_connection_name>
preserve: keep replica path unchanged

V1 behavior applies this only to the flat path field in each replica definition.

Runtime Connection Resolver

By default, commands use config('litestream.connections').

If you need resolve the connections at run time, use resolveConnectionsUsing:

use Eznix86\Litestream\Facades\Litestream;

Litestream::resolveConnectionsUsing(function (array $connections): array {
    return array_merge($connections, [
        'analytics' => [
            'name' => 'analytics',
            'replicas' => ['s3'],
            'path_mode' => 'append',
        ],
    ]);
});

This is useful when you want to:

add runtime-specific connections on top of static config ex. Multi-tenants
filter which configured connections run in a given context
fully replace config connections from another source at runtime.

To return to config-only behavior:

Litestream::forgetConnectionResolver();

Commands

For native command behavior and all flags, refer to Litestream's upstream command docs:

Testing and Quality

Run tests:

vendor/bin/pest

Run static analysis:

vendor/bin/phpstan analyse --memory-limit=1G

Run formatting checks:

vendor/bin/pint --test

Run refactoring checks:

vendor/bin/rector process --dry-run

License

This package is open-sourced software licensed under the MIT license.

eznix86 / laravel-litestream

Maintainers

Details