Migration from Litestream

Walrust and Litestream solve the same problem using the same LTX file format. This guide helps you migrate from Litestream to walrust.

Why Migrate?

Consider walrust if:

Memory-constrained environments - walrust uses 19 MB vs Litestream’s 36 MB (47% reduction)
Multi-database setups - walrust uses 20 MB for 100 databases vs Litestream’s 160 MB (88% reduction)
Simpler configuration - TOML-based configuration

Stay with Litestream if:

You need its mature ecosystem and community
You need SFTP or Azure Blob storage backends

Compatibility

What’s Compatible

Both tools use the same:

LTX file format - walrust can read Litestream backups
WAL-based replication - same underlying mechanism
S3 storage layout - similar directory structure
GFS retention - same retention policy model

What’s Different

Feature	Litestream	Walrust
Memory (1 DB)	36 MB	19 MB
Memory (100 DBs)	160 MB	20 MB
Language	Go	Rust
Config format	YAML	TOML
Metrics	Prometheus	Prometheus

Feature Comparison

Supported in Both

✅ WAL-based continuous replication
✅ S3-compatible storage (AWS, Tigris, R2, MinIO)
✅ Point-in-time recovery (PITR)
✅ GFS retention policy
✅ Multiple databases per process
✅ Checksum verification (SHA256)
✅ Prometheus metrics

Litestream Only

❌ SFTP/Azure Blob storage backends

Walrust Only

✅ Python API (pip install walrust)
✅ Read replicas with polling (walrust replicate)
✅ Disk cache for upload queue (optional)
✅ Webhook notifications for failures
✅ Circuit breaker for S3 failures
✅ Structured exit codes (0-6)

Migration Steps

1. Install Walrust

# Rust
cargo install walrust

# Python (optional)
pip install walrust

Verify installation:

walrust --version

2. Stop Litestream

# systemd
sudo systemctl stop litestream

# Docker
docker stop litestream

3. Convert Configuration

Litestream uses YAML, walrust uses TOML.

Litestream config (litestream.yml):

dbs:
  - path: /data/app.db
    replicas:
      - name: s3
        type: s3
        bucket: my-backups
        path: app.db
        endpoint: https://fly.storage.tigris.dev
        retention:
          hourly: 24
          daily: 7
          weekly: 12
          monthly: 12
        snapshot-interval: 1h
        sync-interval: 1s

Walrust config (walrust.toml):

[s3]
bucket = "s3://my-backups"
endpoint = "https://fly.storage.tigris.dev"

[sync]
snapshot_interval = 3600  # 1 hour in seconds
wal_sync_interval = 1     # 1 second

[retention]
hourly = 24
daily = 7
weekly = 12
monthly = 12

[[databases]]
path = "/data/app.db"
prefix = "app.db"  # Matches Litestream's path

4. Verify S3 Credentials

Both tools use standard AWS environment variables:

export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_ENDPOINT_URL_S3=https://fly.storage.tigris.dev  # for Tigris

5. Test Restore (Optional)

Before switching, test that walrust can read your Litestream backups:

walrust restore app.db \
  --bucket my-backups \
  -o /tmp/test.db \
  --endpoint https://fly.storage.tigris.dev

If this works, walrust is compatible with your existing backups.

6. Start Walrust

# CLI
walrust watch /data/app.db \
  --bucket my-backups \
  --endpoint https://fly.storage.tigris.dev

# Or with config file
walrust watch --config walrust.toml

7. Update systemd Service (if applicable)

Old (Litestream):

[Service]
ExecStart=/usr/local/bin/litestream replicate

New (Walrust):

[Service]
ExecStart=/usr/local/bin/walrust watch \
  /data/app.db \
  --bucket my-backups \
  --endpoint https://fly.storage.tigris.dev

Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart walrust
sudo systemctl status walrust

8. Monitor for Issues

Watch logs:

# systemd
sudo journalctl -u walrust -f

# Docker
docker logs -f walrust

# Direct
export RUST_LOG=walrust=info
walrust watch /data/app.db --bucket my-backups

Check that snapshots are being uploaded:

walrust list --bucket my-backups --endpoint https://fly.storage.tigris.dev

Configuration Mapping

Global Settings

Litestream	Walrust	Notes
`addr` (metrics)	`--metrics-port`	Default: 16767
`log-level`	`RUST_LOG` env	Use `RUST_LOG=walrust=info`

Replica Settings

Litestream	Walrust	Notes
`bucket`	`[s3].bucket`	Add `s3://` prefix in walrust
`endpoint`	`[s3].endpoint`	Same format
`path`	`[[databases]].prefix`	S3 prefix for database
`snapshot-interval`	`[sync].snapshot_interval`	Seconds in walrust
`sync-interval`	`[sync].wal_sync_interval`	Seconds in walrust
`retention`	`[retention]`	Same structure
`validation-interval`	`[sync].validation_interval`	Seconds in walrust

Database Settings

Litestream	Walrust	Notes
`dbs[].path`	`[[databases]].path`	Same
Per-DB snapshot interval	`[[databases]].snapshot_interval`	Override global
Per-DB retention	`[[databases]].retention`	Override global

Command Mapping

Litestream Command	Walrust Equivalent
`litestream replicate`	`walrust watch`
`litestream snapshots <db>`	`walrust list --bucket <bucket>`
`litestream restore <db> <path>`	`walrust restore <db> -o <path> --bucket <bucket>`
`litestream restore -timestamp <time>`	`walrust restore --point-in-time <time>`
`litestream databases`	`walrust list --bucket <bucket>`
`litestream version`	`walrust --version`
`litestream generations`	(Not implemented)
`litestream wal`	(Not implemented)

Advanced Migration

Migrating Multiple Databases

Litestream:

dbs:
  - path: /data/app.db
  - path: /data/users.db
  - path: /data/analytics.db

Walrust:

[[databases]]
path = "/data/app.db"

[[databases]]
path = "/data/users.db"

[[databases]]
path = "/data/analytics.db"

Or use wildcards:

[[databases]]
path = "/data/*.db"

Per-Database Configuration

Litestream:

dbs:
  - path: /data/critical.db
    replicas:
      - name: s3
        snapshot-interval: 5m  # More frequent
        retention:
          hourly: 48
  - path: /data/logs.db
    replicas:
      - name: s3
        snapshot-interval: 1h  # Less frequent

Walrust:

[[databases]]
path = "/data/critical.db"
snapshot_interval = 300  # 5 minutes
retention = { hourly = 48, daily = 7, weekly = 12, monthly = 12 }

[[databases]]
path = "/data/logs.db"
snapshot_interval = 3600  # 1 hour (inherits global retention)

Docker Compose

Litestream:

services:
  litestream:
    image: litestream/litestream
    command: replicate
    volumes:
      - app-data:/data
      - ./litestream.yml:/etc/litestream.yml

Walrust:

services:
  walrust:
    image: walrust
    command: watch /data/app.db --bucket my-backups
    volumes:
      - app-data:/data:ro
    environment:
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
      AWS_ENDPOINT_URL_S3: https://fly.storage.tigris.dev

Rollback Plan

If you need to roll back to Litestream:

Stop walrust:

sudo systemctl stop walrust

Restart Litestream:

sudo systemctl start litestream

Your existing backups are unchanged - Litestream will continue from the last TXID

Both tools use the same LTX format, so they’re fully interchangeable.

Performance Comparison

Based on benchmarks (100KB databases, syncing to Tigris S3):

Metric	Litestream	Walrust	Reduction
Memory (1 DB)	36 MB	19 MB	47%
Memory (10 DBs)	55 MB	19 MB	65%
Memory (100 DBs)	160 MB	20 MB	88%
CPU (idle)	<1%	<1%	-
CPU (active)	2-5%	2-5%	-
Sync latency (P95)	~1s	~1s	-

See Benchmark Results for methodology and detailed data.

Getting Help

Litestream resources:

Walrust resources:

What’s Next?

After migrating:

Test your backups - Run periodic test restores
Set up monitoring - Use Prometheus metrics endpoint
Enable validation - Configure validation_interval to verify backups
Optimize retention - Adjust retention policy based on your needs