Marmot: Distributed SQLite Replication with NATS

Summary

Marmot is a distributed SQLite replicator that provides leaderless, eventually consistent replication built on NATS JetStream. It enables scaling read-heavy SQLite applications by allowing multiple nodes to read and write to their local databases. This innovative approach offers fault tolerance and simplifies scaling without requiring a single primary node.

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

Marmot is an open-source, distributed SQLite replicator written in Go, designed to bring robust, leaderless, and eventually consistent replication to your SQLite databases. Built on top of the fault-tolerant NATS JetStream, Marmot allows you to easily scale out read-heavy applications that rely on SQLite, making this ubiquitous database even more powerful for server-side use cases. It acts as a side-car to your existing processes, capturing changes via triggers and streaming them across your cluster.

Installation

Getting started with Marmot is straightforward. You can download the latest release directly from the GitHub repository.

First, download and extract the package:

tar vxzf marmot-v*.tar.gz

Examples

To see Marmot in action, navigate to the extracted directory and run the provided example cluster script:

./examples/run-cluster.sh

You can then make changes to one database, for instance /tmp/marmot-1.db:

sqlite3 /tmp/marmot-1.db
INSERT INTO Books (title, author, publication_year) VALUES ('Pride and Prejudice', 'Jane Austen', 1813);

Observe these changes propagating to another database, like /tmp/marmot-2.db:

sqlite3 /tmp/marmot-2.db
SELECT * FROM Books;

Marmot supports bidirectional replication, allowing you to make changes interchangeably and see them propagate across nodes. For more advanced use cases and demos, explore the "Out in wild" section on the official documentation, including examples like 2-node HA for edge Kubernetes and Scaling PocketBase with Marmot on Fly.io.

Why use Marmot?

Marmot differentiates itself from other SQLite replication solutions like rqlite, dqlite, and LiteFS through its unique design philosophy:

Leaderless Replication: Unlike solutions requiring a single primary node for all writes, Marmot operates without a primary. Any node can make changes to its local database, and Marmot captures these changes using triggers, streaming them to NATS.
Eventually Consistent: Marmot prioritizes availability and performance by being eventually consistent. This means no global locking or blocking of nodes, allowing for high throughput. While transactions spanning multiple tables might not have serializability guarantees, the "last writer wins" principle applies to individual row changes.
Seamless Integration: It requires no changes to your existing SQLite application logic for reading or writing. You interact with your SQLite database as you normally would.
Fault-Tolerant: Built on NATS JetStream, Marmot leverages NATS's inherent fault tolerance for reliable message streaming and replication.
Comprehensive Snapshot & Recovery: Marmot offers robust snapshot and recovery capabilities with support for various storage options, including NATS Blob Storage, WebDAV, SFTP, and S3-compatible services like AWS S3, Minio, and Blackblaze.

While Marmot offers significant advantages, it's important to note some current limitations: schema changes are not automatically propagated, selective table watching is not supported, and WAL mode is required for reliable multi-process changes.