API changes

.NET Client breaking changes

The TigerBeetle .NET Client 0.17.0 introduced the following breaking changes:

• The enum types CreateAccountResult and CreateTransferResult, with the status codes for the create_accounts and create_transfers operations respectively, were renamed to CreateAccountStatus and CreateTransferStatus.

  The enum value Ok, present in both enum types, was replaced by the new status code Created, which indicates that the event was successfully created.

  Type	Before	After
  Enum	CreateAccountResult	CreateAccountStatus
  Enum Value	CreateAccountResult.Ok	CreateAccountStatus.Created
  Enum	CreateTransferResult	CreateTransferStatus
  Enum Value	CreateTransferResult.Ok	CreateTransferStatus.Created

• The result types CreateAccountsResult and CreateTransfersResult were renamed to the singular form, CreateAccountResult and CreateTransferResult.

  The property Index was removed, since each result value corresponds to an event in the batch at the same index.

  Additional changes include the new Timestamp property and renaming the Result property to Status, reflecting the change to the associated enums.

  Type	Before	After
  Struct	CreateAccountsResult	CreateAccountResult
  Property	CreateAccountsResult.Index	removed
  Property	NA	CreateAccountResult.Timestamp
  Property	CreateAccountsResult.Result	CreateAccountResult.Status
  Struct	CreateTransfersResult	CreateTransferResult
  Property	CreateTransfersResult.Index	removed
  Property	NA	CreateTransferResult.Timestamp
  Property	CreateTransfersResult.Result	CreateTransferResult.Status

• Non-batched methods of the Client class that received a single event such as CreateAccount, CreateTransfer, LookupAccount, and LookupTransfer were removed.

  The batched versions that take an array of events such as CreateAccounts, CreateTransfers, LookupAccounts, and LookupTransfers remain unchanged.

• New exceptions were introduced for conditions that can be handled by the application. The PacketStatus enum is now internal and the RequestException was made abstract.

  The client can be explicitly closed by calling Client.Close(), whereas previously the only way to close a client was through Client.Dispose(). Interacting with a closed client now throws a ClientClosedException instead of an ObjectDisposedException.

  Type	Before	After
  Enum	PacketStatus	removed
  Exception	RequestException	removed
  Method	added	Client.Close()
  Exception		ClientClosedException
  Exception		ClientEvictedException
  Exception		ClientReleaseException
  Exception		TooMuchDataException

Example:

Before:

CreateTransfersResult[] transferErrors = client.CreateTransfers(transfers);
if (transferErrors.Length > 0) {
    // Error handling ...
}

After:

CreateTransferResult[] transferResults = client.CreateTransfers(transfers);
Assert.AreEqual(transferResults.Length, transfers.Length);
foreach(CreateTransferResult result in transferResults)
{
    switch(result.Status)
    {
        case CreateTransferStatus.Created:
        case CreateTransferStatus.Exists:
            // Successfully created.
            break;
        default:
            // Could not be created.
            break;
    }
}

For more details, please refer to the .NET client reference page.

Go Client breaking changes

The TigerBeetle Go Client 0.17.0 introduced the following breaking changes:

• The enum types CreateAccountResult and CreateTransferResult, with the status codes for the create_accounts and create_transfers operations respectively, were renamed to CreateAccountStatus and CreateTransferStatus.

  The enum values AccountOK and TransferOK, were replaced by the new status codes AccountCreated and TransferCreated, which indicates the event was successfully created by the operation.

  Type	Before	After
  Enum	CreateAccountResult	CreateAccountStatus
  Enum Value	AccountOK	AccountCreated
  Enum	CreateTransferResult	CreateTransferStatus
  Enum Value	TransferOK	TransferCreated

• The result types AccountEventResult and TransferEventResult were renamed to CreateAccountResult and CreateTransferResult.

  The field Index was removed, since each result value corresponds to an event in the batch at the same index.

  Additional changes include the new Timestamp field and renaming the Result field to Status, reflecting the change to the associated enums.

  Type	Before	After
  Type	AccountEventResult	CreateAccountResult
  Field	AccountEventResult.Index	removed
  Field	NA	CreateAccountResult.Timestamp
  Field	AccountEventResult.Result	CreateAccountResult.Status
  Type	TransferEventResult	CreateTransferResult
  Field	TransferEventResult.Index	removed
  Field	NA	CreateTransferResult.Timestamp
  Field	TransferEventResult.Result	CreateTransferResult.Status

• The types and errors packages were removed, consolidating all definitions under the root tigerbeetle_go package.

  The Err types were removed in favor of simple value declarations for error codes, allowing the use of idiomatic constructions such as errors.Is(err, ErrTooMuchData).

• Conversions between UInt128 and big.Int now return and accept a pointer to a big integer *big.Int, making the API more idiomatic.

  Type	Before	After
  Function	BigInt() big.Int	BigInt() *big.Int
  Function	BigIntToUint128(value big.Int) Uint128	BigIntToUint128(value *big.Int) Uint128

Example:

Before:

import (
    . "github.com/tigerbeetle/tigerbeetle-go"
    . "github.com/tigerbeetle/tigerbeetle-go/pkg/types"
)

var transferErrors []TransferEventResult
var err error

transferErrors, err = client.CreateTransfers(transfers);
if err != nil {
    // Request error ...
}
if len(transferErrors) > 0 {
    // Error handling ...
}

After:

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

var transferResults []CreateTransferResult
var err error

transferResults, err = client.CreateTransfers(transfers);
if err != nil {
    // Request error ...
}
for _, result := range transferResults {
    switch result.Status {
    case TransferCreated, TransferExists:
        // Successfully created.
    default:
        // Could not be created.
    }
}

For more details, please refer to the Go client reference page.

Java Client breaking changes

The TigerBeetle Java Client 0.17.0 introduced the following breaking changes:

• The enum types CreateAccountResult and CreateTransferResult, with the status codes for the create_accounts and create_transfers operations respectively, were renamed to CreateAccountStatus and CreateTransferStatus.

  The enum value Ok, present in both enum types, was replaced by the new status code Created, which indicates that the event was successfully created.

  Type	Before	After
  Enum	CreateAccountResult	CreateAccountStatus
  Enum Value	CreateAccountResult.Ok	CreateAccountStatus.Created
  Enum	CreateTransferResult	CreateTransferStatus
  Enum Value	CreateTransferResult.Ok	CreateTransferStatus.Created

• The result types CreateAccountResultBatch and CreateTransferResultBatch, had the getIndex() property removed, since each result value corresponds to one event in the batch at the same index.

  Additional changes include the new getTimestamp() property and renaming the getResult() property to getStatus(), reflecting the change to the associated enums.

  Type	Before	After
  Method	CreateAccountResultBatch.getIndex()	removed
  Method	NA	CreateAccountResultBatch.getTimestamp()
  Method	CreateAccountResultBatch.getResult()	CreateAccountResultBatch.getStatus()
  Method	CreateTransferResultBatch.getIndex()	removed
  Method	NA	CreateTransferResultBatch.getTimestamp()
  Method	CreateTransferResultBatch.getResult()	CreateTransferResultBatch.getStatus()

• All the blocking methods of the Client class (such as createAccounts, createTransfers, and others) may throw the checked exception InterruptedException to signal that the waiting thread was interrupted by the Java environment. The non-blocking versions of the same methods that return a CompletableFuture<T> remain unchanged.

• New exceptions were introduced for conditions that can be handled by the application. The PacketStatus enum is now internal and the RequestException was removed.

  All operations throw ClientClosedException instead of IllegalStateException if the client is closed.

  Type	Before	After
  Enum	PacketStatus	removed
  Exception	RequestException	abstract class
  Exception	ClientClosedException	extends RequestException
  Exception		ClientEvictedException
  Exception		ClientReleaseException
  Exception		TooMuchDataException

Example:

Before:

CreateTransferResultBatch transferErrors = client.createTransfers(transfers);
if (transferErrors.getLength() > 0) {
    // Error handling ...
}

After:

try {
    CreateTransferResultBatch transferResults = client.createTransfers(transfers);
    assert transferResults.getLength() == transfers.getLength();
    while (transferResults.next()) {
        switch (transferResults.getStatus()) {
            case Created:
            case Exists:
                // Successfully created.
                break;
            default:
                // Could not be created.
                break;
        }
    }
} catch (InterruptedException exception) {
    // The thread was interrupted.
}

For more details, please refer to the Java client reference page.

Node.js Client breaking changes

The TigerBeetle Node.js Client 0.17.0 introduced the following breaking changes:

• The enum types CreateAccountError and CreateTransferError, with the status codes for the create_accounts and create_transfers operations respectively, were renamed to CreateAccountStatus and CreateTransferStatus.

  The enum value ok, present in both enum types, was replaced by the new status code created, which indicates that the event was successfully created.

  Type	Before	After
  Enum	CreateAccountError	CreateAccountStatus
  Enum Value	CreateAccountError.ok	CreateAccountStatus.created
  Enum	CreateTransferError	CreateTransferStatus
  Enum Value	CreateTransferError.ok	CreateTransferStatus.created

• The result types CreateAccountsError and CreateTransfersError were renamed to CreateAccountResult and CreateTransferResult.

  The field index was removed, since each result value corresponds to an event in the batch at the same index.

  Additional changes include the new timestamp field and renaming the result field to status, reflecting the change to the associated enums.

  Type	Before	After
  Type	CreateAccountsError	CreateAccountResult
  Field	CreateAccountsError.index	removed
  Field	NA	CreateAccountResult.timestamp
  Field	CreateAccountsError.result	CreateAccountResult.status
  Type	CreateTransfersError	CreateTransferResult
  Field	CreateTransfersError.index	removed
  Field	NA	CreateTransferResult.timestamp
  Field	CreateTransfersError.result	CreateTransferResult.status

• New error type RequestError was introduced for conditions that can be handled by the application. Match the RequestError.code property against the constants defined in ErrorCodes to determine the specific failure.

  Type	Before	After
  Type		ErrorCodes
  Error		RequestError

Example:

Before:

const transferErrors: CreateTransfersError[] = await client.createTransfers(transfers);
if (transferErrors.length > 0) {
    // Error handling ...
}

After:

const transferResults: CreateTransferResult[] = await client.createTransfers(transfers);
assert.strictEqual(transferResults.length, transfers.length);
for (const result of transferResults) {
    switch (result.status) {
        case CreateTransferStatus.created:
        case CreateTransferStatus.exists:
            // Successfully created.
            break;
        default:
            // Could not be created.
            break;
    }
}

For more details, please refer to the Node.js client reference page.

Python Client breaking changes

The TigerBeetle Python Client 0.17.0 introduced the following breaking changes:

• The enum types CreateAccountResult and CreateTransferResult, with the status codes for the create_accounts and create_transfers operations respectively, were renamed to CreateAccountStatus and CreateTransferStatus.

  The enum value OK, present in both enum types, was replaced by the new status code CREATED, which indicates that the event was successfully created.

  Type	Before	After
  Enum	CreateAccountResult	CreateAccountStatus
  Enum Value	CreateAccountResult.OK	CreateAccountStatus.CREATED
  Enum	CreateTransferResult	CreateTransferStatus
  Enum Value	CreateTransferResult.OK	CreateTransferStatus.CREATED

• The result types CreateAccountsResult and CreateTransfersResult were renamed to the singular form, CreateAccountResult and CreateTransferResult.

  The field index was removed, since each result value corresponds to an event in the batch at the same index.

  Additional changes include the new timestamp field and renaming the result field to status, reflecting the change to the associated enums.

  Type	Before	After
  Type	CreateAccountsResult	CreateAccountResult
  Field	CreateAccountsResult.index	removed
  Field	NA	CreateAccountResult.timestamp
  Field	CreateAccountsResult.result	CreateAccountResult.status
  Type	CreateTransfersResult	CreateTransferResult
  Field	CreateTransfersResult.index	removed
  Field	NA	CreateTransferResult.timestamp
  Field	CreateTransfersResult.result	CreateTransferResult.status

• The constant amount_max was renamed to AMOUNT_MAX.

• New exceptions were introduced for conditions that can be handled by the application. The PacketStatus enum is now internal and the PacketError exception was removed.

  Type	Before	After
  Enum	PacketStatus	removed
  Exception	PacketError	removed
  Exception		ClientEvictedError
  Exception		ClientReleaseTooLowError
  Exception		ClientReleaseTooHighError
  Exception		TooMuchDataError

• Removed all default initialization values from the types AccountFilter and QueryFilter.

Example:

Before:

transfer_errors = client.create_transfers(transfers)
if len(transfer_errors) > 0:
    # Error handling ...

After:

transfer_results = client.create_transfers(transfers)
assert len(transfer_results) == len(transfers)
for result in transfer_results:
    if result.status == tb.CreateAccountResult.CREATED or \
       result.status == tb.CreateAccountResult.EXISTS:
        # Successfully created.
    else:
        # Could not be created.

For more details, please refer to the Python client reference page.

Rust Client breaking changes

The TigerBeetle Rust Client 0.17.0 also introduced the new API. However, the Rust client is not yet publicly available on Crates.io at the time of this release, so they are not considered breaking changes.

For more details, please refer to the Rust client reference page.