TigerBeetle

https://docs.tigerbeetle.com
Admin
TigerBeetle is a financial transactions database designed for mission-critical safety and...
Tokens:120,236
Snippets:1,358
Trust Score:9.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Go Module and Get TigerBeetle Client

Source: https://docs.tigerbeetle.com/coding/clients/go

Installs the TigerBeetle client for Go. Ensure you are in your project directory.

```bash
go mod init tbtest
go get github.com/tigerbeetle/tigerbeetle-go
```

--------------------------------

### Docker Compose Output Example

Source: https://docs.tigerbeetle.com/operating/deploying/docker

Example output when starting a multi-node TigerBeetle cluster using Docker Compose.

```text
docker-compose up
Starting tigerbeetle_0   ... done
Starting tigerbeetle_2   ... done
Recreating tigerbeetle_1 ... done
Attaching to tigerbeetle_0, tigerbeetle_2, tigerbeetle_1
tigerbeetle_1    | info(io): opening "0_1.tigerbeetle"...
tigerbeetle_2    | info(io): opening "0_2.tigerbeetle"...
tigerbeetle_0    | info(io): opening "0_0.tigerbeetle"...
tigerbeetle_0    | info(main): 0: cluster=0: listening on 0.0.0.0:3001
tigerbeetle_2    | info(main): 2: cluster=0: listening on 0.0.0.0:3003
tigerbeetle_1    | info(main): 1: cluster=0: listening on 0.0.0.0:3002
tigerbeetle_0    | info(message_bus): connected to replica 1
tigerbeetle_0    | info(message_bus): connected to replica 2
tigerbeetle_1    | info(message_bus): connected to replica 2
tigerbeetle_1    | info(message_bus): connection from replica 0
tigerbeetle_2    | info(message_bus): connection from replica 0
tigerbeetle_2    | info(message_bus): connection from replica 1
tigerbeetle_0    | info(clock): 0: system time is 83ns ahead
tigerbeetle_2    | info(clock): 2: system time is 83ns ahead
tigerbeetle_1    | info(clock): 1: system time is 78ns ahead

... and so on ...
```

--------------------------------

### Run Python Application

Source: https://docs.tigerbeetle.com/single-page

Execute the main Python script after setup.

```bash
python3 main.py
```

--------------------------------

### Basic Go Program Setup

Source: https://docs.tigerbeetle.com/coding/clients/go

A minimal Go program to verify the TigerBeetle client import.

```go
package main

import (
    "fmt"
    "log"
    "os"

    . "github.com/tigerbeetle/tigerbeetle-go"
)

func main() {
    fmt.Println("Import ok!")
}
```

--------------------------------

### Verify TigerBeetle Client Setup

Source: https://docs.tigerbeetle.com/coding/clients/dotnet

A minimal C# program to verify that the TigerBeetle client library has been successfully installed and can be imported.

```csharp
using System;
using TigerBeetle;

// Validate import works.
Console.WriteLine("SUCCESS");
```

--------------------------------

### Initialize Project and Install Client

Source: https://docs.tigerbeetle.com/single-page

Creates a new console application and adds the TigerBeetle package dependency.

```bash
dotnet new console
dotnet add package tigerbeetle
```

--------------------------------

### Install TigerBeetle on Linux

Source: https://docs.tigerbeetle.com/operating/installing

Downloads and extracts the Linux binary, then verifies the installation.

```bash
curl -Lo tigerbeetle.zip https://linux.tigerbeetle.com && unzip tigerbeetle.zip
./tigerbeetle version
```

--------------------------------

### TigerBeetle Server Startup Output

Source: https://docs.tigerbeetle.com/single-page

Example output indicating the server is listening on the specified address.

```text
info(io): opening "0_0.tigerbeetle"...
info(main): 0: cluster=0: listening on 0.0.0.0:3000
```

--------------------------------

### Run Docker Compose Up

Source: https://docs.tigerbeetle.com/operating/deploying/docker

Command to start the services defined in the docker-compose.yml file.

```bash
docker-compose up
```

--------------------------------

### Run Docker Compose

Source: https://docs.tigerbeetle.com/single-page

Commands to start the multi-node cluster and view the startup logs.

```bash
docker-compose up
```

```text
docker-compose up
Starting tigerbeetle_0   ... done
Starting tigerbeetle_2   ... done
Recreating tigerbeetle_1 ... done
Attaching to tigerbeetle_0, tigerbeetle_2, tigerbeetle_1
tigerbeetle_1    | info(io): opening "0_1.tigerbeetle"...
tigerbeetle_2    | info(io): opening "0_2.tigerbeetle"...
tigerbeetle_0    | info(io): opening "0_0.tigerbeetle"...
tigerbeetle_0    | info(main): 0: cluster=0: listening on 0.0.0.0:3001
tigerbeetle_2    | info(main): 2: cluster=0: listening on 0.0.0.0:3003
tigerbeetle_1    | info(main): 1: cluster=0: listening on 0.0.0.0:3002
tigerbeetle_0    | info(message_bus): connected to replica 1
tigerbeetle_0    | info(message_bus): connected to replica 2
tigerbeetle_1    | info(message_bus): connected to replica 2
tigerbeetle_1    | info(message_bus): connection from replica 0
tigerbeetle_2    | info(message_bus): connection from replica 0
tigerbeetle_2    | info(message_bus): connection from replica 1
tigerbeetle_0    | info(clock): 0: system time is 83ns ahead
tigerbeetle_2    | info(clock): 2: system time is 83ns ahead
tigerbeetle_1    | info(clock): 1: system time is 78ns ahead

... and so on ...
```

--------------------------------

### Install TigerBeetle .NET Client

Source: https://docs.tigerbeetle.com/coding/clients/dotnet

Installs the TigerBeetle client package for a new .NET console application. This command should be run after creating a new project directory.

```bash
dotnet new console
dotnet add package tigerbeetle
```

--------------------------------

### Start TigerBeetle Replicas

Source: https://docs.tigerbeetle.com/operating/deploying

Starts the TigerBeetle replicas for a three-replica cluster. The `--addresses` argument must be identical for all replicas and clients, with the order corresponding to the replica index.

```bash
./tigerbeetle start --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 ./0_0.tigerbeetle &
./tigerbeetle start --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 ./0_1.tigerbeetle &
./tigerbeetle start --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 ./0_2.tigerbeetle &
```

--------------------------------

### Deploy a three-replica cluster on a single machine

Source: https://docs.tigerbeetle.com/single-page

Downloads the binary, formats three data files, and starts three replica processes in the background.

```bash
curl -Lo tigerbeetle.zip https://linux.tigerbeetle.com && unzip tigerbeetle.zip && ./tigerbeetle version
./tigerbeetle format --cluster=0 --replica-count=3 --replica=0 ./0_0.tigerbeetle
./tigerbeetle format --cluster=0 --replica-count=3 --replica=1 ./0_1.tigerbeetle
./tigerbeetle format --cluster=0 --replica-count=3 --replica=2 ./0_2.tigerbeetle

./tigerbeetle start --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 ./0_0.tigerbeetle &
./tigerbeetle start --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 ./0_1.tigerbeetle &
./tigerbeetle start --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 ./0_2.tigerbeetle &
```

--------------------------------

### BigInt Usage Examples

Source: https://docs.tigerbeetle.com/coding/clients/node

Demonstrates the use of BigInt literals and the BigInt constructor for 64-bit integer support.

```javascript
1n
```

```javascript
BigInt(1)
```

--------------------------------

### Configure account flags

Source: https://docs.tigerbeetle.com/single-page

Examples of using the AccountFlags struct to generate a uint16 bitfield for account configuration.

```go
AccountFlags{Linked: true}.ToUint16()
AccountFlags{DebitsMustNotExceedCredits: true}.ToUint16()
AccountFlags{CreditsMustNotExceedDebits: true}.ToUint16()
AccountFlags{History: true}.ToUint16()
```

--------------------------------

### Maven Project Setup (pom.xml)

Source: https://docs.tigerbeetle.com/coding/clients/java

Configure your Maven project to include the TigerBeetle Java client library. Ensure Java 11 and Maven 3.6+ are installed.

```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.tigerbeetle</groupId>
  <artifactId>samples</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
  </properties>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <compilerArgs>
            <arg>-Xlint:all,-options,-path</arg>
          </compilerArgs>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>1.6.0</version>
        <configuration>
          <mainClass>com.tigerbeetle.samples.Main</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>com.tigerbeetle</groupId>
      <artifactId>tigerbeetle-java</artifactId>
      <!-- Grab the latest commit from: https://repo1.maven.org/maven2/com/tigerbeetle/tigerbeetle-java/maven-metadata.xml -->
      <version>0.0.1-3431</version>
    </dependency>
  </dependencies>
</project>
```

--------------------------------

### Create linked accounts with constraints

Source: https://docs.tigerbeetle.com/single-page

Shows how to link multiple accounts and apply specific constraints using account flags.

```go
account0 := Account{
    ID:     ToUint128(100),
    Ledger: 1,
    Code:   718,
    Flags: AccountFlags{
        DebitsMustNotExceedCredits: true,
        Linked:                     true,
    }.ToUint16(),
}
account1 := Account{
    ID:     ToUint128(101),
    Ledger: 1,
    Code:   718,
    Flags: AccountFlags{
        History: true,
    }.ToUint16(),
}

accountResults, err := client.CreateAccounts([]Account{account0, account1})
// Results handling omitted.
```

--------------------------------

### Install TigerBeetle dependencies

Source: https://docs.tigerbeetle.com/single-page

Command to install the configured Maven dependencies.

```bash
mvn install
```

--------------------------------

### Install TigerBeetle Gem

Source: https://docs.tigerbeetle.com/coding/clients/ruby

Command to install the TigerBeetle client library.

```bash
gem install tigerbeetle
```

--------------------------------

### Create a single account

Source: https://docs.tigerbeetle.com/single-page

Demonstrates the basic structure for creating a single account using the client.

```go
accountResults, err := client.CreateAccounts([]Account{
    {
        ID:          ID(), // TigerBeetle time-based ID.
        UserData128: ToUint128(0),
        UserData64:  0,
        UserData32:  0,
        Ledger:      1,
        Code:        718,
        Flags:       0,
        Timestamp:   0,
    },
})
// Results handling omitted.
```

--------------------------------

### Create and Lookup Accounts in TigerBeetle REPL

Source: https://docs.tigerbeetle.com/start

Demonstrates creating two accounts and then looking them up using the TigerBeetle REPL. Shows the initial state of the accounts.

```shell
> create_accounts id=1 code=10 ledger=700, id=2 code=10 ledger=700;
> lookup_accounts id=1, id=2;
```

--------------------------------

### Install TigerBeetle on macOS

Source: https://docs.tigerbeetle.com/operating/installing

Downloads and extracts the macOS binary, then verifies the installation.

```bash
curl -Lo tigerbeetle.zip https://mac.tigerbeetle.com && unzip tigerbeetle.zip
./tigerbeetle version
```

--------------------------------

### Create Accounts in Go

Source: https://docs.tigerbeetle.com/coding/clients/go

Demonstrates creating multiple accounts in a single batch request. Handles success, existing accounts, and errors, logging the timestamp or status for each.

```go
account0 := Account{
    ID:     ToUint128(102),
    Ledger: 1,
    Code:   718,
    Flags:  0,
}
account1 := Account{
    ID:     ToUint128(103),
    Ledger: 1,
    Code:   718,
    Flags:  0,
}
account2 := Account{
    ID:     ToUint128(104),
    Ledger: 1,
    Code:   718,
    Flags:  0,
}

accountResults, err := client.CreateAccounts([]Account{account0, account1, account2})
if err != nil {
    log.Printf("Error creating accounts: %s", err)
    return
}

for i, result := range accountResults {
    switch result.Status {
    case AccountCreated:
        log.Printf("Batch account at %d successfully created with timestamp %d.", i, result.Timestamp)
    case AccountExists:
        log.Printf("Batch account at %d already exists with timestamp %d.", i, result.Timestamp)
    default:
        log.Printf("Batch account at %d failed to create: %s", i, result.Status)
    }
}
```

--------------------------------

### Install TigerBeetle on Windows

Source: https://docs.tigerbeetle.com/operating/installing

Downloads and extracts the Windows binary using PowerShell, then verifies the installation.

```powershell
powershell -command "curl.exe -Lo tigerbeetle.zip https://windows.tigerbeetle.com; Expand-Archive tigerbeetle.zip ."
.\tigerbeetle version
```

--------------------------------

### Create Accounts

Source: https://docs.tigerbeetle.com/single-page

Demonstrates creating accounts by defining an array of Account objects and submitting them via the client.

```csharp
var accounts = new[] {
    new Account
    {
        Id = ID.Create(), // TigerBeetle time-based ID.
        UserData128 = 0,
        UserData64 = 0,
        UserData32 = 0,
        Ledger = 1,
        Code = 718,
        Flags = AccountFlags.None,
        Timestamp = 0,
    },
};

var accountResults = client.CreateAccounts(accounts);
// Results handling omitted.
```

--------------------------------

### Install Python Client Package

Source: https://docs.tigerbeetle.com/operating/upgrading

Command to install or update the TigerBeetle Python client package to a specific version.

```bash
pip install tigerbeetle==0.15.4
```

--------------------------------

### Install Node.js Client Package

Source: https://docs.tigerbeetle.com/operating/upgrading

Command to install or update the TigerBeetle Node.js client package to a specific version.

```bash
npm install --save-exact tigerbeetle-node@0.15.4
```

--------------------------------

### Handle batch account creation results

Source: https://docs.tigerbeetle.com/single-page

Demonstrates how to process the results of a batch account creation and handle potential errors.

```go
account0 := Account{
    ID:     ToUint128(102),
    Ledger: 1,
    Code:   718,
    Flags:  0,
}
account1 := Account{
    ID:     ToUint128(103),
    Ledger: 1,
    Code:   718,
    Flags:  0,
}
account2 := Account{
    ID:     ToUint128(104),
    Ledger: 1,
    Code:   718,
    Flags:  0,
}

accountResults, err := client.CreateAccounts([]Account{account0, account1, account2})
if err != nil {
    log.Printf("Error creating accounts: %s", err)
    return
}

for i, result := range accountResults {
    switch result.Status {
    case AccountCreated:
        log.Printf("Batch account at %d successfully created with timestamp %d.", i, result.Timestamp)
    case AccountExists:
        log.Printf("Batch account at %d already exists with timestamp %d.", i, result.Timestamp)
    default:
        log.Printf("Batch account at %d failed to create: %s", i, result.Status)
    }
}
```

--------------------------------

### Install TigerBeetle Python Client

Source: https://docs.tigerbeetle.com/coding/clients/python

Install the TigerBeetle client library using pip. Ensure you have Python 3.7 or higher.

```bash
pip install tigerbeetle
```

--------------------------------

### Start TigerBeetle Replica

Source: https://docs.tigerbeetle.com/start

Starts a single-replica TigerBeetle cluster listening on port 3000. The data is stored in the specified file. It's safe to interrupt with ^C.

```bash
./tigerbeetle start --addresses=3000 --development ./0_0.tigerbeetle
```

--------------------------------

### Create a single account

Source: https://docs.tigerbeetle.com/coding/clients/rust

Demonstrates the basic syntax for creating an account using the client's create_accounts method.

```rust
let account_results = client
    .create_accounts(&[tb::Account {
        id: tb::id(),
        ledger: 1,
        code: 718,
        ..Default::default()
    }])?
    .await?;
// Result handling omitted.
```

--------------------------------

### Build and Run Project

Source: https://docs.tigerbeetle.com/single-page

Compiles and executes the .NET console application.

```bash
dotnet run
```

--------------------------------

### Upgrade TigerBeetle Binary Installation

Source: https://docs.tigerbeetle.com/operating/upgrading

Steps to upgrade a binary-based TigerBeetle installation on each replica. This includes downloading the new binary, replacing the old one, and restarting the service if necessary.

```bash
# SSH to each replica, in no particular order:
cd /tmp
wget https://github.com/tigerbeetle/tigerbeetle/releases/download/0.15.4/tigerbeetle-x86_64-linux.zip
unzip tigerbeetle-x86_64-linux.zip

# Put the binary on the same file system as the target, so mv is atomic.
mv tigerbeetle /usr/bin/tigerbeetle-new

mv /usr/bin/tigerbeetle /usr/bin/tigerbeetle-old
mv /usr/bin/tigerbeetle-new /usr/bin/tigerbeetle

# Restart TigerBeetle. Only required when upgrading from 0.15.3.
# Otherwise, it will detect new versions are available and coordinate the upgrade itself.
systemctl restart tigerbeetle # or, however you are managing TigerBeetle.
```

--------------------------------

### Start TigerBeetle AMQP CDC Job

Source: https://docs.tigerbeetle.com/operating/cdc

Use this command to start the CDC job, streaming transfers and balance updates to an AMQP broker. Ensure the AMQP broker is accessible and configured with the specified exchange.

```bash
./tigerbeetle amqp --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 --cluster=0 \
    --host=127.0.0.1 \
    --vhost=/ \
    --user=guest --password=guest \
    --publish-exchange=tigerbeetle
```

--------------------------------

### Recover TigerBeetle Replica

Source: https://docs.tigerbeetle.com/operating/recovering

Use this command to recover a replica if its data file is permanently lost. Ensure the cluster is healthy and capable of view-changing before running this command. After successful recovery, start the replica normally with `tigerbeetle start`.

```bash
./tigerbeetle recover \
  --cluster=0 \
  --addresses=127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002 \
  --replica=2 \
  --replica-count=3 \
  ./0_2.tigerbeetle
```

--------------------------------

### Create Accounts with TigerBeetle .NET Client

Source: https://docs.tigerbeetle.com/coding/clients/dotnet

Demonstrates creating multiple accounts in a batch and handling the results, including success, existing accounts, and failures.

```csharp
var account0 = new Account
{
    Id = 102,
    Ledger = 1,
    Code = 1,
    Flags = AccountFlags.None,
};
var account1 = new Account
{
    Id = 103,
    Ledger = 1,
    Code = 1,
    Flags = AccountFlags.None,
};
var account2 = new Account
{
    Id = 104,
    Ledger = 1,
    Code = 1,
    Flags = AccountFlags.None,
};

var accountResults = client.CreateAccounts(new[] { account0, account1, account2 });
for (int i = 0; i < accountResults.Length; i++)
{
    switch (accountResults[i].Status)
    {
        case CreateAccountStatus.Created:
            Console.WriteLine($"Batch account at {i} successfully created with timestamp {accountResults[i].Timestamp}.");
            break;
        case CreateAccountStatus.Exists:
            Console.WriteLine($"Batch account at {i} already exists with timestamp {accountResults[i].Timestamp}.");
            break;
        default:
            Console.WriteLine($"Batch account at {i} failed to create: {accountResults[i].Status}");
            break;
    }
}
```

--------------------------------

### Example CDC Message Body (JSON)

Source: https://docs.tigerbeetle.com/operating/cdc

This is a formatted example of the JSON message body published by the CDC job. Note that actual published messages are UTF-8 encoded JSON without line breaks or spaces, and long integers are encoded as JSON strings.

```json
{
  "timestamp": "1745328372758695656",
  "type": "single_phase",
  "ledger": 2,
  "transfer": {
    "id": 9082709,
    "amount": 3794,
    "pending_id": 0,
    "user_data_128": "79248595801719937611592367840129079151",
    "user_data_64": "13615171707598273871",
    "user_data_32": 3229992513,
    "timeout": 0,
    "code": 20295,
    "flags": 0,
    "timestamp": "1745328372758695656"
  },
  "debit_account": {
    "id": 3750,
    "debits_pending": 0,
    "debits_posted": 8463768,
    "credits_pending": 0,
    "credits_posted": 8861179,
    "user_data_128": "118966247877720884212341541320399553321",
    "user_data_64": "526432537153007844",
    "user_data_32": 4157247332,
    "code": 1,
    "flags": 0,
    "timestamp": "1745328270103398016"
  },
  "credit_account": {
    "id": 6765,
    "debits_pending": 0,
    "debits_posted": 8669204,
    "credits_pending": 0,
    "credits_posted": 8637251,
    "user_data_128": "43670023860556310170878798978091998141",
    "user_data_64": "12485093662256535374",
    "user_data_32": 1924162092,
    "code": 1,
    "flags": 0,
    "timestamp": "1745328270103401031"
  }
}
```

--------------------------------

### Create linked accounts with flags

Source: https://docs.tigerbeetle.com/single-page

Demonstrates creating multiple accounts in a single batch while applying bitwise-or flags to enforce constraints.

```java
AccountBatch accounts = new AccountBatch(2);

accounts.add();
accounts.setId(100);
accounts.setLedger(1);
accounts.setCode(718);
accounts.setFlags(AccountFlags.LINKED | AccountFlags.DEBITS_MUST_NOT_EXCEED_CREDITS);

accounts.add();
accounts.setId(101);
accounts.setLedger(1);
accounts.setCode(718);
accounts.setFlags(AccountFlags.HISTORY);

CreateAccountResultBatch accountResults = client.createAccounts(accounts);
// Results handling omitted.
```

--------------------------------

### Build and run the project

Source: https://docs.tigerbeetle.com/coding/clients/rust

Command to compile and execute the Rust project.

```bash
cargo run
```

--------------------------------

### Verify TigerBeetle Installation

Source: https://docs.tigerbeetle.com/coding/clients/ruby

Basic script to verify that the gem is correctly required.

```ruby
require "tigerbeetle"

puts("Import OK!")
```

--------------------------------

### Create and Lookup Accounts

Source: https://docs.tigerbeetle.com/single-page

Initialize two accounts with specific IDs and ledger codes, then verify their creation.

```text
> create_accounts id=1 code=10 ledger=700, id=2 code=10 ledger=700;
> lookup_accounts id=1, id=2;
```

--------------------------------

### Create Multiple Accounts with Flags in Java

Source: https://docs.tigerbeetle.com/coding/clients/java

This example shows how to create multiple accounts in a single batch, applying different flags like LINKED and DEBITS_MUST_NOT_EXCEED_CREDITS. Combine enum values using bitwise-OR for flags.

```java
AccountBatch accounts = new AccountBatch(2);

accounts.add();
accounts.setId(100);
accounts.setLedger(1);
accounts.setCode(718);
accounts.setFlags(AccountFlags.LINKED | AccountFlags.DEBITS_MUST_NOT_EXCEED_CREDITS);

accounts.add();
accounts.setId(101);
accounts.setLedger(1);
accounts.setCode(718);
accounts.setFlags(AccountFlags.HISTORY);

CreateAccountResultBatch accountResults = client.createAccounts(accounts);
// Results handling omitted.
```

--------------------------------

### TigerBeetle Format Output

Source: https://docs.tigerbeetle.com/single-page

Example output after successfully formatting a data file.

```text
info(io): creating "0_0.tigerbeetle"...
info(io): allocating 660.140625MiB...
```
Tokens:
Raw