Marmot v2: a leaderless SQLite replication server that speaks MySQL

The problem Marmot v2 targets: multi-region writes without leader election

MySQL active-active replication needs conflict avoidance rules, monitoring, and manual failover, and a split-brain event is resolved by an operator. Marmot v2 removes the election entirely. It is a leaderless, distributed SQLite replication system built on a gossip protocol, and the README states that any node can accept writes. There is no primary to promote and no failover step to run.

The intended audience is narrow and stated plainly. The README lists distributed WordPress, Lambda and edge sidecars, edge vector databases, regional config servers, and product catalogs as the cases where the design fits. The common shape is a read-heavy workload with several regional copies of the same small database, where a write accepted locally and replicated shortly after is good enough. A single-region OLTP system with a high write rate is not that shape, and the README sends that reader to PostgreSQL or MySQL directly.

Gossip membership, two-phase commit, and last-write-wins conflict resolution

The mechanism has three parts. Cluster membership uses SWIM-style gossip, so nodes learn about each other without a coordinator. Writes go through two-phase commit with a consistency level chosen per operation: ONE, QUORUM, or ALL. Conflicts resolve by last-write-wins using hybrid logical clock timestamps, and the README describes automatic recovery from split-brain through eventual consistency plus anti-entropy rather than through operator intervention.

The write path itself is Percolator-style. A transaction writes intents, conflict detection runs against those intents, and the intents are committed. The repository layout reflects this: coordinator/, cluster/, hlc/, and replica/ are separate top-level directories, and go.mod lists grpc and protobuf for node-to-node traffic, nats.go and kafka-go for messaging, and cockroachdb/pebble as the local store. Replication is row-level change data capture, which is a different approach from the page-level interception used by some SQLite replication tools.

The SQL layer is where most of the dependency weight sits. go.mod pulls in vitess.io/vitess and rqlite/sql, and the README says the parser is the rqlite/sql AST parser handling MySQL to SQLite transpilation. That is the piece that makes a MySQL client work against a SQLite file, and it is also the piece most likely to reject a query you assumed would pass.

Installing Marmot v2 and running a two-node replication check

The README's quick start runs a single node from the built binary, then connects with a MySQL client on port 3306.

./marmot-v2
mysql -h localhost -P 3306 -u root

The binary reads config.toml, and the repository ships config.toml.example alongside it plus per-node examples such as examples/node-1-config.toml. To run it in the background instead, the README gives a daemon flag with a pid file:

./marmot-v2 -daemon -pid-file=/tmp/marmot/marmot.pid

For a real replication check, the repository provides example scripts rather than instructions to assemble by hand. The seed node starts on port 8081 with MySQL on 3307, and a second node joins it explicitly.

./examples/start-seed.sh
./examples/join-cluster.sh 2 localhost:8081
mysql --protocol=TCP -h localhost -P 3307 -u root

After joining, run a CREATE TABLE and an INSERT on the first node, then query the second node's MySQL port. If the row is there, gossip, commit, and CDC replication are all working end to end. There is also a scripted version, ./scripts/test-ddl-replication.sh, which the README says starts a two-node cluster and checks DDL and DML in both directions. Cleanup is pkill -f marmot-v2. Note that the README documents no uninstall or data migration path, and the example scripts assume the binary is already built. For building from source, the repository has build-linux.sh at the top level; the README does not spell out the Go build invocation.

MySQL compatibility is the adoption lever, and also the sharpest edge

The MySQL wire interface is what makes Marmot v2 practical for existing software. DBeaver, MySQL Workbench, and the mysql CLI connect without a shim, and the README claims WordPress runs unmodified against it. To back that claim the project implements a specific function set: date and time functions including NOW, CURDATE, DATE_FORMAT, UNIX_TIMESTAMP, DATEDIFF, YEAR, MONTH, and DAY; string functions including CONCAT_WS, SUBSTRING_INDEX, FIND_IN_SET, LPAD, and RPAD; math and hash functions including RAND, MD5, SHA1, SHA2, and POW; and ON DUPLICATE KEY UPDATE, which is transformed into SQLite's ON CONFLICT clause.

That list is the honest boundary of the compatibility story. It is a curated set aimed at WordPress, not a general MySQL emulation layer, and the README does not claim otherwise. If your application calls stored procedures, triggers, or MySQL-specific functions outside that set, the transpiler is where the failure will surface, and it will surface at query time rather than at connect time.

The WordPress example also exposes the operational split. The README is explicit that media uploads are not replicated by Marmot and should live on S3 or NFS, and that sessions need Redis or database-backed sessions for load balancing without sticky sessions. Database replication is the part Marmot covers; the rest of the stack still needs its own shared storage.

Where Marmot v2 is the wrong tool

Last-write-wins conflict resolution is a real limitation, and it is the one most likely to bite silently. Two nodes accepting writes to the same row means one write is discarded, chosen by hybrid logical clock timestamp. There is no merge and no error surfaced to the losing client. For counters, inventory decrements, or any workload where concurrent writes to the same row must both take effect, this is a correctness bug rather than a performance trade-off.

The README's own exclusion list is short and worth taking literally. Strong serializability sends you to CockroachDB or Spanner. Single-region high-throughput work sends you to PostgreSQL or MySQL. Datasets above roughly 100GB send you to a sharded solution. Marmot v2 is SQLite underneath, with SQLite's write serialization on each node and its file-size expectations.

There is a maturity signal in the release list that a reader should weigh. The three most recent releases are all beta versions, v2.9.14-beta through v2.9.16-beta, dated 2026-09-01 to 2026-09-02. The project is not archived and the last push was on 2026-09-15, so it is being worked on, but the published artifacts carry a beta label. Treat the consistency behavior under partition as something to test on your own workload rather than assume.

How Marmot v2 differs from rqlite, dqlite, and LiteFS

The README draws the comparison directly. rqlite, dqlite, and LiteFS require a primary node for all writes and use Raft leader election; Marmot v2 accepts writes on any node and uses gossip instead. The other tools also sit behind a proxy layer or intercept at the page level, while Marmot v2 exposes the MySQL protocol for direct database access.

That difference has consequences in both directions. Removing leader election removes the failover step and the coordination overhead, which is what makes edge deployment plausible. It also removes the single ordering authority, which is why conflict resolution has to exist at all. A Raft-based system gives you a linearizable write path and a leader that can be slow to elect; Marmot gives you local write acceptance and last-write-wins. Neither is strictly better, and the README's framing that leaderless is the improvement is a design position rather than a measured result.

The second difference is the access path. Because clients speak MySQL, an existing ORM or GUI tool works without a new driver. The cost is that every query passes through MySQL to SQLite transpilation, so compatibility is bounded by the parser and the implemented function set rather than by the wire protocol alone.

Licence, maintenance, and what an upgrade actually costs

Marmot v2 is MIT licensed, which places few restrictions on commercial use, modification, or redistribution. The repository also vendors a module at modules/vecindex for the built-in vector search, and go.mod lists a large indirect dependency tree including vitess, pebble, grpc, nats, and kafka clients. Under MIT those dependencies keep their own licences, so a redistribution that bundles the binary carries their notices too. That is a packaging question for your legal team, not a conclusion here.

The maintenance picture from the available facts: not archived, last push on 2026-09-15, and a run of beta releases in early September 2026. The upgrade cost is dominated by the storage and protocol layers rather than by the API. Pebble is the local store, CDC drives replication, and cluster membership runs over gossip, so a version bump can change on-disk format or replication semantics in ways that matter across a mixed-version cluster. The README does not document rollback, and it does not describe a mixed-version upgrade procedure. If you run more than one node, upgrade the whole cluster together and take a copy of the SQLite files first.

Editorial conclusion

Adopt Marmot v2 when you want SQLite replicas in several regions, local reads, and writes accepted on any node without leader election, and when eventual consistency with last-write-wins is acceptable. Do not adopt it when you need strong serializability, a single-region high-throughput primary, or datasets beyond roughly 100GB, all of which the README points elsewhere for. Before committing, verify the consistency mode you intend to run under load, confirm your schema and queries survive the MySQL to SQLite transpilation, and check what your clients do when a node rejoins after a partition.

Frequently asked questions

Official sources

1. License: MIT
2. maxpert/marmot on GitHub
3. Project website
4. README
5. Releases