Skip to content

Latest commit

 

History

History
127 lines (80 loc) · 4.29 KB

DEEP_DIVE.md

File metadata and controls

127 lines (80 loc) · 4.29 KB

Install TigerBeetle, benchmark! and work your way through six demos...

Video walkthrough

Video walkthrough on Youtube

Clone TigerBeetle

git clone https://github.com/coilhq/tigerbeetle.git
cd tigerbeetle

Upgrade Ubuntu to the 5.7.15 kernel

Get Ubuntu 20.04 to a recent kernel with io_uring. This should take less than a minute:

scripts/upgrade_ubuntu_kernel

For newer than 5.7.15, you can also find the full list of mainline releases here, but note that kernel 5.7.16 and up introduced a network performance regression that has recently been patched.

Install Zig

scripts/install_zig

You can also re-run the script above to update your Zig to latest master. Zig has a rapid release cadence at present and we are tracking master to keep pace.

Simulate non-pristine lab conditions

You are ready to rock! To simulate non-pristine lab conditions (tiger beetles thrive in harsh environments with noisy neighbors) turn up your favorite album, or if you're looking for something new we suggest Noel Gallagher's High Flying Birds.

Be aware that super non-pristine lab conditions such as an active video call might cause cache pollution and drop throughput. But rock 'n roll is generally fine.

Benchmark!

Launch the server with a clean journal:

rm -rf journal && ./tigerbeetle

In another tab:

zig run src/benchmark.zig -O ReleaseSafe

After each run of the benchmark, you must delete TigerBeetle's journal data file and restart the server to ensure a clean journal. The benchmark will abort if any accounts or transfers already exist.

Explore the API through six demos

Take a look at the source code of these demos before you run them. Check out our screencast of these demos for much more detail.

Let's turn up the log level some more (and your favorite album) so you can see everything the server does as you run these demos:

  • Open src/config.zig in your editor and change log_level to 7 (debug).

  • Restart the server with a clean journal: rm -rf journal && ./tigerbeetle

Demo 1, 2: Create and lookup accounts

Let's create some accounts and check their balances and limits:

zig run src/demo_01_create_accounts.zig
zig run src/demo_02_lookup_accounts.zig

What happens if we create those accounts again?

zig run src/demo_01_create_accounts.zig

Demo 3: Simple journal entries

Let's create some simple double-entry accounting journal entries (with auto-commit transfers):

zig run src/demo_03_auto_commit_transfers.zig
zig run src/demo_02_lookup_accounts.zig

Demo 4, 5, 6: Two-phase commit journal entries

Let's try full two-phase commit transfers (create, and then commit):

These two-phase commit transfers are designed for two-phase commit systems such as Mojaloop, where the fulfil packet only includes the transfer id and you want to avoid a lookup query roundtrip to the database before writing the compensating journal entry.

You will see the second transfer is rejected with an error for tripping the debit reserved limit.

zig run src/demo_04_create_transfers.zig
zig run src/demo_02_lookup_accounts.zig

You will see these two-phase transfers only update the inflight reserved limits.

Let's commit (and accept):

Again, the second transfer is rejected because it was never created.

zig run src/demo_05_accept_transfers.zig
zig run src/demo_02_lookup_accounts.zig

Let's also pretend someone else tried to commit (but reject) concurrently:

zig run src/demo_06_reject_transfers.zig

From here, feel free to tweak these demos and see what happens. You can explore all our accounting invariants (and the DSL we created for these) in src/state.zig by grepping the source for fn create_account, fn create_transfer, and fn commit_transfer.

Enjoy...