Single-node RF=1 yugabyted or pinned three-node Docker Compose cluster for repeatable YugabyteDB development?

Direct Recommendation

Use single-node yugabyted with RF=1 and a fresh temporary data directory for every developer machine. Reserve the three-node Docker Compose RF=3 cluster for CI pipelines and pre-merge integration tests. This split gives you sub-second startup for the inner loop while still exercising distributed behavior where it matters—before code merges.

What RF=1 Hides (and Why It Matters)

Testing exclusively against RF=1 leaves these production code paths unexercised:

• Tablet splitting and rebalancing — default 10 GB threshold is never hit on tiny dev datasets.
• Raft leader election latency — no follower promotion, no election timeouts.
• Follower reads — yb_read_from_followers=on or AS OF FOLLOWER clauses silently read from the leader.
• Distributed transaction coordinator failover — single-node has no coordinator redundancy.
• Geo-partitioning placement rules — yb_servers() returns one row; any tooling that assumes multiple zones breaks.
• CDC and PITR — both require RF ≥ 3 and will no-op or error on RF=1.

If your application uses any of the above, you must run the three-node cluster in CI.

Repeatability: Wipe Every Time

Mounted volumes hurt repeatability. They preserve stale cluster UUIDs, master leadership leases, and tablet metadata that cause Cluster already initialized errors or schema-version mismatches after an image upgrade. The cleanest pattern:

# Developer machine (Makefile target or shell alias)
yugabyted destroy --base_dir=/tmp/yb_dev 2>/dev/null || true
yugabyted start --base_dir=$(mktemp -d) --replication_factor=1
# then run idempotent migration/seed scripts against localhost:5433

In CI, use the official three-node compose file with no persistent volumes:

docker compose -f yugabyte-db-cluster.yaml up --force-recreate --remove-orphans
# wait for health checks, then run the SAME migration/seed scripts

Add docker compose down -v in the teardown step to guarantee a clean slate.

Pinning the Image Tag Is Not Enough

Pinning yugabytedb/yugabyte:2024.1.0-b123 (or better, by digest sha256:…) fixes the binary, but YugabyteDB may change RocksDB SST layout, catalog schema, or tablet metadata between minor versions. A clean wipe is still required when the pinned tag/digest changes. Check the release notes for the specific version at docs.yugabyte.com to see if an on-disk format change is listed.

Verification Checklist

1. Single-node: yugabyted status shows Replication Factor: 1 and Tablet Servers: 1.
2. Three-node: docker compose exec yb-master-1 yb-admin --master_addresses yb-master-1:7100,yb-master-2:7100,yb-master-3:7100 list_tablet_servers returns three entries.
3. Run SELECT * FROM yb_servers(); on port 5433 — RF=1 returns one row, RF=3 returns three with cloud,region,zone populated.
4. In CI, kill a tserver (docker compose kill yb-tserver-2) and verify the app reconnects without error.
5. After changing the pinned tag, run the destroy/down‑-v step before starting; confirm no Cluster already initialized errors appear.

One Diagnostic Detail

Does your application enable yb_read_from_followers or use AS OF FOLLOWER reads in production? If yes, you cannot rely on RF=1 even for daily development—run the three-node cluster locally (or accept that those code paths are CI-only).