A PostgreSQL-inspired database replication engine featuring write-ahead logging (WAL), leader-follower replication, automatic failover, conflict resolution, split-brain detection, and cluster management — all built from scratch in TypeScript.
┌─────────────────────────────────────────────────────────┐
│ Cluster Manager │
│ leader election · failover · split-brain detection │
│ partition simulation · health monitoring │
├─────────────────────────────────────────────────────────┤
│ Replication Layer │
│ WAL streaming · snapshot sync · conflict resolution │
├──────────┬───────────────────┬──────────────────────────┤
│ Leader │ Follower (1) │ Follower (2) │
│ R/W │ R/O + sync │ R/O + sync │
├──────────┴───────────────────┴──────────────────────────┤
│ Write-Ahead Log (WAL) │
│ append-only · LSN tracking · checkpoints │
├─────────────────────────────────────────────────────────┤
│ Transaction Manager │
│ begin/commit/abort · UNDO via before-images │
├─────────────────────────────────────────────────────────┤
│ Storage Engine │
│ in-memory tables · snapshots · predicate scans │
└─────────────────────────────────────────────────────────┘
| Component | Complexity | Description |
|---|---|---|
| WAL append | O(1) | Append-only log with monotonic LSN |
| WAL replay | O(n) | Sequential scan from LSN checkpoint |
| Leader election | O(n log n) | Sort by LSN, tie-break by node ID |
| Replication | O(k × m) | k followers × m new WAL records |
| Conflict detection | O(n × m) | Cross-product of local/remote records |
| Snapshot sync | O(d) | Full database serialization |
| Split-brain heal | O(n) | Single pass leader deduplication |
- Synchronous: Leader waits for all followers to acknowledge before returning. Strongest consistency, highest latency.
- Asynchronous: Leader returns immediately after local WAL write. Lowest latency, potential data loss on failover.
- Semi-synchronous: Leader waits for at least one follower. Balance of consistency and performance.
Leader fails → Detect offline → Elect new leader (highest LSN)
→ Reassign followers → Incremental sync → Resume writes
→ Old leader recovers → Full/incremental sync → Rejoin as follower
npm install
npm run build
npm run demo # Full interactive demo
node dist/main.js bench # Benchmark replication throughput
node dist/main.js cluster # Show cluster topologynpm testThe demo command walks through a complete replication lifecycle:
- Create a 3-node cluster (1 leader, 2 followers)
- Show cluster topology (ASCII art)
- Execute writes on leader with WAL records
- Verify replication to followers
- Query all nodes for consistent reads
- Simulate leader failure
- Automatic failover with leader election
- Continue writes on new leader
- Recover old leader via full sync
- Detect and heal split-brain
- Transaction commit and abort
- Conflict resolution (last-writer-wins)
- Cluster health report with alerts
- Replication statistics
src/
├── main.ts # CLI entry point
├── wal/
│ ├── record.ts # WAL record types and serialization
│ ├── log.ts # Write-ahead log implementation
│ └── transaction.ts # Transaction manager (begin/commit/abort)
├── storage/
│ └── table.ts # In-memory table and database engine
├── replica/
│ ├── node.ts # Replica node with leader/follower roles
│ └── conflict.ts # Conflict detection and resolution
└── cluster/
├── manager.ts # Cluster management, election, failover
└── monitor.ts # Health monitoring and alerting
tests/
└── test_replication.ts # 25 comprehensive tests
Mo Shirmohammadi
MIT