django-litestream

---

This package installs and integrates litestream, the SQLite replication tool, as a Django command.

Table of Contents

• django-litestream
  • Table of Contents
  • Installation
  • Usage
    • Configuration
      • Configuration Examples
    • Commands
      • litestream config
      • litestream databases
      • litestream ltx
      • litestream replicate
      • litestream restore
      • litestream status
      • litestream sync
      • litestream mcp
      • litestream version
      • litestream verify
      • litestream vfs-install
    • VFS Read Replicas
  • License

Installation

pip install django-litestream

Add django_litestream to your Django INSTALLED_APPS.

Usage

The package integrates all the commands and options from the litestream command-line tool with only minor changes.

Note

Django 5.1 was released a few days ago (as of the time of writing). If you are looking for a good production configuration for SQLite, check out this blog post.

Configuration

These are the available configurations for django-litestream:

# settings.py
LITESTREAM = {
    "path_prefix": "",
    "bin_path": "./venv/bin/litestream",
    "dbs": [{"path": "default"}],
    # ... all other Litestream configuration options
}

Important

All litestream commands automatically use the configuration from your Django settings. Configuration is dynamically generated when you run commands - no config file needed!

The path_prefix is a string that will be prepended to the path of every database in the dbs configuration. This is useful if you are replicating databases from different projects to the same bucket, you could set the path_prefix to the project name so that the databases are stored in different folders in the bucket.

The bin_path is the path to the Litestream binary. If not found, the binary will be automatically downloaded on first use. You can specify a custom installation path here if needed.

All other configuration options (such as dbs, logging, addr, mcp-addr, access-key-id, secret-access-key, etc.) follow the same structure as the Litestream configuration file. You can use any option documented in the official Litestream configuration reference.

Configuration Examples

Simple configuration with auto-generated replica:

# settings.py
LITESTREAM = {
    "dbs": [
        {"path": "default"},  # Use Django database alias
    ]
}
# This will use environment variables for S3 credentials:
# - LITESTREAM_REPLICA_BUCKET (or AWS_BUCKET)
# - LITESTREAM_ACCESS_KEY_ID (or AWS_ACCESS_KEY_ID)
# - LITESTREAM_SECRET_ACCESS_KEY (or AWS_SECRET_ACCESS_KEY)

Manual replica configuration:

# settings.py
LITESTREAM = {
    "dbs": [
        {
            "path": "default",  # Django alias
            "replica": {
                "type": "s3",
                "bucket": "my-bucket",
                "path": "db.sqlite3",
                "region": "us-east-1",
            }
        }
    ]
}

Multiple databases with path_prefix:

# settings.py
DATABASES = {
    "default": {"ENGINE": "django.db.backends.sqlite3", "NAME": BASE_DIR / "db.sqlite3"},
    "cache": {"ENGINE": "django.db.backends.sqlite3", "NAME": BASE_DIR / "cache.sqlite3"},
}

LITESTREAM = {
    "path_prefix": "myproject",  # Prepended to replica paths
    "dbs": [
        {"path": "default"},  # Will replicate to myproject/db.sqlite3
        {
            "path": "cache",
            "replica": {
                "type": "s3",
                "bucket": "my-cache-bucket",
                "path": "custom-cache.sqlite3",
            }
        }
    ]
}

For the example above the dynamically generated configuration will look like this (assuming BASE_DIR is /home/tobi/myproject):

access-key-id: $LITESTREAM_ACCESS_KEY_ID
secret-access-key: $LITESTREAM_SECRET_ACCESS_KEY
dbs:
- path: /home/tobi/myproject/db.sqlite3
  replica:
    type: s3
    bucket: $LITESTREAM_REPLICA_BUCKET
    path: myproject/db.sqlite3
- path: /home/tobi/myproject/cache.sqlite3
  replica:
    type: s3
    bucket: "my-cache-bucket"
    path: custom-cache.sqlite3

You can tweak these settings according to your preferences. Check the databases settings reference for more information.

You can omit the access-key-id and secret-access-key keys and litestream will automatically use any of the environment variables below if available:

• AWS_ACCESS_KEY_ID or LITESTREAM_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY or LITESTREAM_SECRET_ACCESS_KEY

Commands

You can run python manage.py litestream to see all available commands.

litestream config

python manage.py litestream config

This command displays the current Litestream configuration that will be used by all commands. It shows the configuration generated from your Django settings in YAML format. This is useful for:

• Verifying your configuration before running replication
• Debugging configuration issues
• Understanding what will be passed to the Litestream binary

The output matches the format of a litestream.yml file.

litestream databases

This works exactly like the equivalent litestream command and lists all the databases.

Examples:

python manage.py litestream databases

Important

For the rest of the commands, wherever you are asked to specify the database path db_path, you can use the Django database alias instead, for example, default instead of /home/tobi/myproject/db.sqlite3.

litestream ltx

Note

LTX support is available in Litestream v0.5.0+.

This works exactly like the equivalent litestream command and lists LTX (Litestream Transaction Log) files available for a database or replica. This command is mainly used for debugging and is not typically used in normal usage.

Examples:

python manage.py litestream ltx default
python manage.py litestream ltx -replica s3 default
python manage.py litestream ltx -level 1 default  # View files at specific compaction level

You can also specify a replica URL directly:

python manage.py litestream ltx s3://mybkt.litestream.io/db

litestream replicate

This works exactly like the equivalent litestream command, except it does not support the ability to replicate a single file. Running litestream replicate db_path replica_url won't work. You can only run:

python manage.py litestream replicate
python manage.py litestream replicate -exec "gunicorn myproject.wsgi:application"
python manage.py litestream replicate -once  # Replicate once and exit
python manage.py litestream replicate -restore-if-db-not-exists  # Restore DB if missing

This is the command you will run in production using a process manager as its own process. You can run it separately (the first example) or use it to run your main Django process (second example). It would basically act as a process manager itself and run both the replicate and the Django process. The replication process will exit when your web server shuts down.

Available flags:

• -exec: Execute a subcommand (Litestream exits when child exits)
• -once: Replicate once and exit
• -force-snapshot: Force a snapshot on startup
• -enforce-retention: Enforce retention policy on startup
• -restore-if-db-not-exists: Restore database from replica if it doesn't exist locally
• --log-level: Set log level (debug, info, warn, error)

litestream restore

This works exactly like the equivalent litestream command.

Examples:

python manage.py litestream restore default
python manage.py litestream restore -if-replica-exists default
python manage.py litestream restore -f default  # Follow mode: continuously restore

Available flags:

• -replica: Restore from specific replica
• -o: Output path of the restored database
• -if-replica-exists: Returns exit code 0 if no backups found
• -if-db-not-exists: Returns exit code 0 if database already exists
• -parallelism: Number of LTX files downloaded in parallel (default: 8)
• -generation: Restore from specific generation
• -index: Restore up to specific LTX index
• -timestamp: Restore to specific point-in-time
• -f: Follow mode - continuously restore/follow the database

litestream status

Show replication status for all databases or a specific database.

python manage.py litestream status
python manage.py litestream status default

litestream sync

Force immediate WAL-to-LTX sync for a database.

python manage.py litestream sync default

This forces the replication process to immediately sync any pending WAL data to LTX files, rather than waiting for the next scheduled sync.

litestream mcp

Note

MCP support is available in Litestream v0.5.0+. This feature is not available in v0.3.13.

The MCP (Model Context Protocol) server allows AI assistants to interact with Litestream databases and replicas through a standardized HTTP API. Unlike other litestream commands, MCP is not a standalone command but a server feature that runs alongside the replicate command.

To enable MCP, add the mcp_addr configuration to your Django settings:

# settings.py
LITESTREAM = {
    "mcp-addr": ":3001",  # Listen on all interfaces
    # or for production (localhost only):
    # "mcp-addr": "127.0.0.1:3001",
}

The MCP server will automatically start when you run the replicate command:

python manage.py litestream replicate

The MCP server exposes several tools for AI assistants:

• litestream_info - Get system status and configuration information
• litestream_databases - List all configured databases and their replica status
• litestream_ltx - View available LTX (transaction log) files for a specific database
• litestream_restore - Restore a database to a specific point in time

For more information about MCP integration and AI assistant setup, visit the official documentation.

litestream version

Print the version of the Litestream binary.

python manage.py litestream version

litestream verify

This command verifies the integrity of your backed-up databases. This process is inspired by the verify command of the litestream-ruby gem. The verification process involves the following steps:

1. Add Verification Data: A new row is added to a _litestream_verification table in the specified database. This table is created if it does not already exist. The row contains a unique code and the current timestamp.
2. Wait for Replication: The command waits for 10 seconds to allow Litestream to replicate the new row to the configured storage providers.
3. Restore Backup: The latest backup is restored from the storage provider to a temporary location.
4. Check Verification Data: The restored database is checked to ensure that the verification row is present. This ensures that the backup is both restorable and up-to-date.

If the verification row is not found in the restored database, the command will return an error indicating that the backup data is out of sync. If the row is found, the command confirms that the backup data is in sync.

Examples:

python manage.py litestream verify default

This check ensures that the restored database file Exists, can be opened by SQLite, and has up-to-date data.

litestream vfs-install

Download and install the Litestream VFS extension for read-only replica access.

python manage.py litestream vfs-install

See the VFS Read Replicas section for more information.

VFS Read Replicas

Note

VFS support requires Litestream v0.5.0+ and is currently in beta.

The VFS (Virtual File System) feature enables read-only access to database replicas stored in cloud object storage without downloading the entire database file. Pages are fetched on-demand and cached in memory.

1. Install the VFS extension:

python manage.py litestream vfs-install

2. Configure VFS replicas:

# settings.py
from django_litestream import get_vfs_databases

LITESTREAM = {
    # Regular replication
    "dbs": [{"path": "default"}],

    # VFS read replicas
    "vfs": {
        "prod_replica": "s3://mybucket/db.sqlite3",
        "analytics_replica": "s3://analytics/db.sqlite3",
    }
}

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    },
    **get_vfs_databases(),  # Adds VFS replicas
}

3. Use VFS replicas in your code:

from myapp.models import User

# Read from VFS replica
users = User.objects.using('prod_replica').all()

# Regular queries use primary database
new_user = User.objects.create(username="alice")

Supported URL formats:

• s3://bucket/path - Amazon S3
• gcs://bucket/path - Google Cloud Storage
• abs://container/path - Azure Blob Storage

Key benefits:

• No download required - pages fetched on-demand
• Memory efficient - only active pages cached
• Auto-updating - polls for changes every second

Limitations:

• VFS replicas are read-only (writes will fail)
• Only x86_64 and arm64 architectures supported

License

django-litestream is distributed under the terms of the MIT license.