TigerBeetle Python Client

0.17.3 verified Sat May 09 auth: no python

The official Python client for TigerBeetle, a high-performance financial accounting database. Current version 0.17.3, released irregularly alongside server updates. Requires Python >=3.7 and a running TigerBeetle server (typically started via Docker).

pip install tigerbeetle

Common errors

error Connection refused: connect() to tcp://127.0.0.1:3000 failed ↓

cause TigerBeetle server is not running or not listening on the expected address.

fix

Start a server: docker run -p 3000:3000 ghcr.io/tigerbeetle/tigerbeetle:0.17.3 start --addresses=0.0.0.0:3000

error ValueError: The server version is incompatible with this client ↓

cause Client and server versions do not match the required compatibility range.

fix

Upgrade both client and server to the same release version or check supported upgrade versions in release notes.

error ImportError: cannot import name 'Client' from 'tigerbeetle' ↓

cause Using an outdated tigerbeetle package or incorrect import path.

fix

Upgrade to latest: pip install --upgrade tigerbeetle, then use from tigerbeetle import Client.

Warnings

breaking Client version must be >=0.16.4 and server version must be >=0.16.78 (for 0.17.3) due to protocol incompatibility. Mismatched versions cause connection errors or data corruption. ↓

fix Always upgrade both client and server together. Check release notes for compatible version pairs.

gotcha Client is not thread-safe; creating multiple clients or sharing a single client across threads leads to undefined behavior. ↓

fix Use one client per thread or synchronize access with locks.

deprecated The Account and Transfer classes from earlier versions are deprecated. Use plain dictionaries with snake_case field names. ↓

fix Replace class instances with dicts as shown in quickstart.

gotcha Account IDs must be 128-bit unsigned integers; using Python ints beyond 2^128-1 will overflow silently. ↓

fix Ensure account IDs fit within 128 bits. Use smaller values or hash IDs to fit.

Imports

Client
wrong
```
import tigerbeetle
```
correct
```
from tigerbeetle import Client
```
Client is the main class, not a module-level function.

CreateAccountResult

from tigerbeetle import CreateAccountResult

Quickstart

Create a TigerBeetle client and create a single account.

import os
from tigerbeetle import Client

client = Client(
    cluster_id=0,
    replica_addresses=[os.environ.get('TB_ADDRESS', '3000')],
)

account = {
    'id': 1,
    'debits_pending': 0,
    'debits_posted': 0,
    'credits_pending': 0,
    'credits_posted': 0,
    'user_data': 0,
    'reserved': 0,
    'ledger': 1,
    'code': 1,
    'flags': 0,
}
create_accounts_result = client.create_accounts([account])
print(create_accounts_result)