TigerBeetle on Parix
Learn the ledger primitives Parix exposes and the managed boundary around them.
TigerBeetle is the ledger database behind every Parix database. Parix does not replace TigerBeetle's account and transfer model with a proprietary abstraction; it exposes the same core records and operations through a managed, authenticated gateway.
Use this page to understand the boundary. For exact request fields and examples, continue to TigerBeetle operations and the live OpenAPI document.
Core records
Accounts
An account represents a balance-bearing entity inside one ledger. Common fields include:
| Field | Purpose |
|---|---|
id | Unique, non-negative account identifier. Use a stable identifier and reuse it when retrying the same create request. |
ledger | Application-defined 32-bit ledger identifier. Transfers require both accounts to use the same ledger. |
code | Application-defined 16-bit account type or classification. |
flags | TigerBeetle account behavior encoded as a bitfield. |
user_data_128, user_data_64, user_data_32 | Optional application metadata that can also be used by query filters. |
| posted and pending debit/credit totals | Server-managed balance fields returned by reads. Do not treat them as client-writable balance mutations. |
Transfers
A transfer moves an integer amount from one account to another.
| Field | Purpose |
|---|---|
id | Unique, non-negative transfer identifier and the basis for idempotent retries. |
debit_account_id | Account that is debited. |
credit_account_id | Account that is credited. |
amount | Non-negative integer amount in your application's smallest unit. |
ledger and code | Application-defined classification that must follow the TigerBeetle data model. |
flags | Transfer behavior such as pending or linked semantics, encoded as a bitfield. |
pending_id and timeout | Fields used by supported pending-transfer flows. |
| user-data fields | Optional application metadata for correlation and queries. |
TigerBeetle stores integers, not decimal currency values. Your application defines the unit—for example, cents or another fixed precision—and applies it consistently.
Identifiers and numeric values
The Parix API accepts non-negative integer strings for TigerBeetle-sized integer fields. Strings are the safest JSON representation for 64- and 128-bit values because JavaScript numbers cannot represent every large integer exactly.
{
"id": "1000000000000000000001",
"ledger": 1,
"code": 100,
"flags": 0
}Generate identifiers in your application and persist them before submitting a write. If a network failure leaves the outcome unknown, retry with the same account or transfer ID rather than creating a new ID.
Operations exposed by Parix
Parix currently exposes eight TigerBeetle operation families:
| Kind | Operations |
|---|---|
| Write | create_accounts, create_transfers |
| Point lookup | lookup_accounts, lookup_transfers |
| Account history | get_account_balances, get_account_transfers |
| Filtered query | query_accounts, query_transfers |
Create and lookup batches contain at least one item and accept up to 8,190 items at the request-schema boundary. Plan-specific event quotas can be lower, so the lower active limit wins. The Dashboard and Metrics pages show shared-plan limits; dedicated limits are governed by the active product contract and gateway configuration.
Read operations require database read access. Create operations require database write access.
Query filters
Account and transfer queries can filter on supported combinations of:
- ledger and code
- user-data fields
- timestamp range
- result limit
- TigerBeetle query flags
Account-history operations additionally require an account_id. The query explorer renders common fields first and keeps flags and less frequently used fields under Advanced.
Write results
TigerBeetle create operations return per-item result information rather than a newly created object body. Interpret the result for every item in a batch.
An empty error result means the submitted items succeeded. A non-empty result identifies the item index and TigerBeetle result code that must be handled. Do not assume the entire batch failed because one item returned a result.
For the exact Parix response envelope, see TigerBeetle operations.
What Parix adds
Parix wraps TigerBeetle with:
- organization and database authorization
- all-database or database-specific API-key scope
- shared-plan quotas and request rate limiting
- provider-aware routing and private gateway connectivity
- a browser query explorer
- provisioning, upgrade, backup, restore, and configuration workflows
- plan-appropriate metrics, logs, notifications, and billing context
The gateway may reject a request before TigerBeetle executes it—for example, for a missing scope, an inactive database, invalid payload, plan quota, rate limit, or unavailable route. Keep Parix gateway errors separate from TigerBeetle per-item create results in your application telemetry.
Access model
Applications never receive direct replica addresses. A client calls the Parix API, and Parix resolves the current shared-cell or dedicated route before forwarding the operation privately to the data plane.
This routing indirection is important for shared-cell placement changes and dedicated lifecycle workflows: the database ID remains the public API target even when Parix changes the backing route.
Design checklist
Before integrating a production workload:
- define stable schemes for account IDs, transfer IDs, ledgers, and codes
- define the smallest integer unit for every ledger
- decide which application facts belong in user-data fields
- reuse identifiers on retries
- inspect every per-item create result
- choose API-key scope and rotation ownership
- handle Parix authentication, quota, rate-limit, route, and lifecycle errors
- keep a reconciliation path that can query accounts and transfers by durable identifiers
Continue with Connect to a database, TigerBeetle operations, or Parix architecture.