litestream

This agent skill provides expert-level assistance for developers and system administrators working with Litestream, the standalone disaster recovery tool for SQLite. It is designed to guide users through the architecture, implementation patterns, and complex troubleshooting scenarios associated with continuous SQLite replication. The agent is trained on core invariants such as the 1GB lock page boundary, LTX (Log Transaction) file immutability, and atomic file operations, ensuring that your replication logic remains consistent and durable.

Use this skill when you need to understand how Litestream monitors the Write-Ahead Log (WAL), how it manages multi-level compaction, or how to implement a custom storage backend using the ReplicaClient interface. Whether you are debugging replication lag, configuring S3/GCS backends, or architecting a robust SQLite deployment for high-availability production environments, this agent provides actionable code patterns and system configuration advice. It effectively replaces the need to manually parse the codebase for low-level interaction details.

• Architectural guidance on the integration of Litestream within Go applications, including proper DB layer management and lock ordering (Store.mu to Replica.mu).

• Deep insights into LTX file formats, transaction IDs (TXID), and checkpointing logic for point-in-time recovery.

• Best practices for testing via race detectors, building custom storage adapters, and handling SQLite page size variations (4KB, 8KB, 16KB, 32KB).

• Support for advanced monitoring setups, including Prometheus metrics and Grafana dashboards, to track WAL byte consumption and sync operations.

• Error handling strategies for distributed systems, including proper wrapping of context errors and management of atomic rename operations.

• Prioritize the use of the modernc.org/sqlite driver to avoid lock conflicts on POSIX systems.

• Adhere to strict immutable LTX file storage policies to maintain backup integrity.

• Always perform local read operations before remote storage access during compaction to optimize for consistency and latency.

• Ensure that the 1GB lock page (0x40000000) is always skipped during any manual page-level manipulation or compaction logic to prevent database corruption.

• Consult the agent for advice on configuring replicas, managing replica lifecycles, and troubleshooting connection pool pragmas like busy_timeout.