# TigerBeetle — Distributed Financial Accounting Database

> Purpose-built OLTP database for double-entry accounting and financial transactions, written in Zig and designed for safety and speed.

## Install

Save in your project root:

# TigerBeetle — Distributed Financial Accounting Database

## Quick Use
```bash
# Format a 3-node cluster data file for node 0
./tigerbeetle format --cluster=0 --replica=0 --replica-count=3 0_0.tigerbeetle

# Start one replica
./tigerbeetle start --addresses=3001,3002,3003 0_0.tigerbeetle

# Use the REPL to create accounts and transfers
./tigerbeetle client --addresses=3001,3002,3003
> create_accounts id=1 ledger=1 code=10,
>                 id=2 ledger=1 code=10;
> create_transfers id=1 debit_account_id=1 credit_account_id=2 amount=100 ledger=1 code=1;
```

## Introduction
TigerBeetle is a distributed financial accounting database written in Zig, designed specifically for business transactions: double-entry bookkeeping, balances, and transfers. It aims to be orders of magnitude faster and safer than general-purpose OLTP databases when the workload is high-contention, high-throughput ledger operations.

## What TigerBeetle Does
- Stores immutable double-entry ledgers of accounts and transfers.
- Performs 1 million financial transactions per second on commodity hardware.
- Replicates state across nodes using the VSR consensus protocol.
- Enforces invariants (debits = credits, balances ≥ 0) as first-class database rules.
- Provides a deterministic simulation test suite ("DST") for chaos-resistant correctness.

## Architecture Overview
TigerBeetle uses the Viewstamped Replication (VSR) protocol for strict-serializable replication. Each replica is a single-threaded state machine executing batched operations with a static memory footprint, zero dynamic allocation, and io_uring-based async I/O. Its LSM-tree storage engine is purpose-built: forest of LSMs per schema, amortized compaction, and direct-I/O writes to the `.tigerbeetle` file.

## Self-Hosting & Configuration
- Clone and build: `git clone https://github.com/tigerbeetle/tigerbeetle && ./zig/download.sh && ./zig/zig build`.
- Run at least 3 replicas (or 5 for higher durability) with `--addresses` for each peer.
- Data files are pre-allocated: `tigerbeetle format` creates a fixed-size `*.tigerbeetle` file per replica.
- Deploy on NVMe with direct I/O enabled; no external storage, cache, or OS tuning required beyond defaults.
- Client SDKs exist for Go, Java, Node.js, Python, .NET, and Zig; batch operations for best throughput.

## Key Features
- Domain-specific schema: only accounts and transfers, which unlock massive optimization.
- Strict serializability and zero data loss under crash and network partition.
- Deterministic Simulation Testing harness catches subtle distributed bugs.
- Static memory and zero-GC design: no page cache surprises, no tail latency spikes.
- Native batching (up to 8,189 ops per request) makes each round-trip count.

## Comparison with Similar Tools
- **Postgres / MySQL** — Great general-purpose OLTP; TigerBeetle is far faster for pure ledger workloads.
- **FoundationDB** — Key-value with ACID; TigerBeetle ships ledger semantics out of the box.
- **CockroachDB / YugabyteDB** — Distributed SQL; TigerBeetle avoids SQL parsing and planning overhead.
- **Amazon QLDB** — Managed immutable ledger; TigerBeetle is OSS, self-hosted, and much faster.
- **Custom ledger microservices** — TigerBeetle replaces these with a correct, tested primitive.

## FAQ
**Q:** Can I model arbitrary entities in TigerBeetle?
A: No — the schema is accounts + transfers by design. Keep application data elsewhere and reference TigerBeetle IDs.

**Q:** Is it really safe for money movement?
A: Yes — deterministic simulation, VSR replication, and fsync-correct I/O are core to the project.

**Q:** How do I integrate with Postgres?
A: Keep Postgres for business data and call TigerBeetle for balances/transfers through its native client SDKs.

**Q:** What happens if a replica loses its disk?
A: Another replica takes over; once the failed node is re-formatted, it catches up through state sync from peers.

## Sources
- https://github.com/tigerbeetle/tigerbeetle
- https://docs.tigerbeetle.com

---
Source: https://tokrepo.com/en/workflows/74ef1123-3931-11f1-9bc6-00163e2b0d79
Author: AI Open Source