Upgrade to Litestream 5.x

[epompeii]

Upgrade to Litestream 5.x (#670)

https://fly.io/blog/litestream-v050-is-here/

This requires changing the replicas array in the server config to a replica object as v0.5.0 drops support for multiple replicas.

[github-actions]

🤖 Claude Code Review

PR: #719
Base: devel
Head: u/ep/litestream-5
Commit: bfda66712b7bca0be59d3fdbfe77a0d517c2ac73

---

Now I have a complete picture of the changes. Here's my review:

---

PR Review: litestream_5.x

Summary

Upgrades Litestream from v0.3.13 to v0.5.10, adapting the configuration model to match the new version's YAML structure. Key changes:

• Removes Azure Blob Storage (abs) and Google Cloud Storage (gcs) replica schemes
• Changes from replicas: Vec<JsonReplica> (multiple) to replica: JsonReplica (single)
• Moves snapshot_interval, retention, validation_interval from per-replica fields to top-level JsonLitestream fields
• Removes retention_check_interval entirely
• Updates download URL format (drops v prefix from filename) and architecture naming (amd64 -> x86_64)
• Updates Dockerfiles, CI, devcontainer, and docs across all 9 languages

Issues

1. Breaking API change without migration path
The change from replicas: [...] to replica: {...} and moving snapshot_interval/retention/validation_interval to top-level are breaking changes to the server configuration schema. Existing users' config files will fail to deserialize. Consider whether a migration or backwards-compatible deserialization (e.g., #[serde(alias = "replicas")]) is needed, or if this is acceptable as a major version bump.

2. retention_check_interval removed from docs but referenced in docs text
The docs at plus-disaster-recovery.mdx still reference retention_check_interval in the prose:

retention_check_interval: (Optional) Specifies how often Bencher will check if retention needs to be enforced. Defaults to 1h.

But this field was removed from the Rust types and OpenAPI spec. The docs text should be updated to remove this reference, or the field should be kept if Litestream 5.x still supports it.

3. std::path::PathBuf used instead of camino::Utf8PathBuf
Per CLAUDE.md: "Use camino (Utf8Path/Utf8PathBuf) for file paths whenever practical." The new code continues using std::path::PathBuf for the path field in JsonLitestream::into_yaml, LitestreamDb, LitestreamReplica::File, and JsonReplica::File. This is pre-existing, but worth noting if you're doing a significant refactor of this module anyway.

4. Single replica is a regression in functionality
The old model supported multiple replicas (e.g., replicate to both S3 and a local file simultaneously). The new model only supports one. If this is an intentional Litestream 5.x limitation, it should be documented. If Litestream 5.x still supports multiple replicas, this is a functional regression.

5. port field dropped from LitestreamReplica::Sftp
The SFTP port is still accepted in JsonReplica::Sftp but is collapsed into the host string as "{host}:{port}" when converting to LitestreamReplica. Verify this host:port format is what Litestream 5.x expects (the old code did the same, so this is likely fine, but worth confirming with the new version).

Positives

• Good test coverage: tests for YAML generation cover S3, file, SFTP, snapshot/validation options, and sanitization of secrets
• Clean removal of the duplicated shared fields (retention, snapshot_interval, etc.) from each variant into top-level config — the new structure is much less repetitive
• OpenAPI spec and docs updated consistently across all 9 languages
• The From<JsonReplica> for LitestreamReplica conversion is much simpler without the #[expect(clippy::too_many_lines)] suppression

Minor

• .github/workflows/ci.yml has a trailing newline added at EOF — harmless but unnecessary
• The into_yaml method creates dbs as a Vec with a single element. If the new model only supports one DB (matching single replica), this could be simplified, though it may be matching Litestream's YAML schema which expects an array.

Verdict

The core refactoring is clean, but items 1 and 2 need attention before merging. The breaking config change needs a migration strategy (or explicit documentation that this is a breaking change), and the stale retention_check_interval reference in the docs should be cleaned up.

---

_{Model: claude-opus-4-6}

[github-actions]

Bencher Report

Branch	u/ep/litestream-5
Testbed	ubuntu-22.04

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
Adapter::Json	📈 view plot 🚷 view threshold	3.82 µs (+8.06%) Baseline: 3.53 µs	4.67 µs (81.67%)
Adapter::Magic (JSON)	📈 view plot 🚷 view threshold	3.73 µs (+6.23%) Baseline: 3.51 µs	4.58 µs (81.27%)
Adapter::Magic (Rust)	📈 view plot 🚷 view threshold	25.67 µs (+0.52%) Baseline: 25.54 µs	31.38 µs (81.81%)
Adapter::Rust	📈 view plot 🚷 view threshold	2.86 µs (+1.41%) Baseline: 2.82 µs	3.29 µs (87.05%)
Adapter::RustBench	📈 view plot 🚷 view threshold	2.85 µs (+0.99%) Baseline: 2.82 µs	3.28 µs (86.90%)
head_version_insert/batch/10	📈 view plot 🚷 view threshold	101.63 µs (+1.22%) Baseline: 100.40 µs	117.94 µs (86.17%)
head_version_insert/batch/100	📈 view plot 🚷 view threshold	240.32 µs (+1.03%) Baseline: 237.87 µs	265.67 µs (90.46%)
head_version_insert/batch/255	📈 view plot 🚷 view threshold	460.27 µs (-0.53%) Baseline: 462.71 µs	498.15 µs (92.40%)
head_version_insert/batch/50	📈 view plot 🚷 view threshold	161.37 µs (+0.10%) Baseline: 161.20 µs	183.26 µs (88.06%)
threshold_query/join/10	📈 view plot 🚷 view threshold	142.85 µs (-1.47%) Baseline: 144.98 µs	169.35 µs (84.35%)
threshold_query/join/20	📈 view plot 🚷 view threshold	159.22 µs (-0.22%) Baseline: 159.57 µs	186.63 µs (85.31%)
threshold_query/join/5	📈 view plot 🚷 view threshold	136.50 µs (-0.47%) Baseline: 137.15 µs	160.16 µs (85.23%)
threshold_query/join/50	📈 view plot 🚷 view threshold	207.97 µs (+3.52%) Baseline: 200.89 µs	231.70 µs (89.76%)

🐰 View full continuous benchmarking report in Bencher