Aster Web Data / Connect your data

TigerBeetlePreview

How Aster Web Data publishes TigerBeetle accounts and transfers, and which reads and writes the ledger can answer.

If you keep balances in a TigerBeetle ledger, Aster Web Data publishes its accounts and transfers as two OData sets, so a screen can list an account's transfers or create a transfer with an ordinary request. The service runs no SQL here: each read or write becomes a request to the cluster, and the cluster's own rules apply. Records are immutable once created, so they can be read and created, but not changed or deleted.

TigerBeetle has no table scan, which shapes every read you design. A read must name an ID, an account, or a field the cluster can query by; a broad list, a count and offset paging are refused with a message that names the alternatives.

Connecting

The catalog is fixed, so a service stored on the ledger declares no data sources:

services:
  ledger:
    datasources: []
databases:
  ledger:
    kind: tigerbeetle
    options:
      cluster_id: '0'             # your cluster's ID
      addresses: 127.0.0.1:3000   # the replica addresses, comma-separated

A URL, the parts form, schema, TLS settings and read_only are refused, and setup takes only existing, because there are no tables to create and both sets accept inserts. pool is accepted and not used: one client serves every call. A service on the ledger also refuses transactional server rules and request-context rules that need a check after the write. The configuration reference lists the shared keys, such as required and retry.

The service uses the official TigerBeetle client, version 0.17.9, and the tests run against a cluster of the same version.

Start-up check

There are no tables to check, and opening the client makes no call to the cluster. The first health check, a lookup of account ID 0 bounded by timeout_ms, is the first call that reaches it. A failed check makes Accounts and Transfers answer 503 ConnectionLost until the ledger is back, while the service's other sets keep serving; A database goes down describes the rest. $metadata is the same whether or not the cluster is reachable.

Accounts and transfers

The two sets use TigerBeetle's own field names.

Identifiers and amounts travel as decimal text, so no value passes through floating point. Every property is required, so there are no nulls. When a record is created, an omitted writable value is zero or false, and id must be supplied. The balance counters, timestamp and linked are set by the cluster. Accounts have no navigations, so $expand does not apply.

Where each operation runs

The service answers these request shapes with a native query to the cluster:

The default page is 1,000 records, and a response holds at most 8,189. On a bounded result such as an ID lookup, the service evaluates any other filter itself, and sums 128-bit values and orders them numerically. String functions on these fields are refused.

These are refused with a 400 that names the alternatives: a read with no ID, account ID or query filter, or filtered only by timestamp; $count=true and /$count; $skip above 0; ordering by a field other than timestamp; and a query that would fill the 8,189-record batch without paging, which is refused rather than returned cut short.

Errors

Writes and transactions

• Creating records. A POST creates one account or transfer, and the response is the record as the cluster stored it. Two-phase transfers use the pending flag, then post_pending_transfer or void_pending_transfer, with pending_id naming the first transfer.
• No updates or deletes. PATCH, PUT and DELETE return 405, with an Allow header that lists the allowed methods, and $metadata reports that updates and deletes are not supported. A ledger set takes no concurrency setting, because no write decides over a stored record that another writer could change.
• Atomic groups. A $batch atomicity group is sent as one native linked chain of 1 to 8,189 inserts, all of accounts or all of transfers, with literal values. The service checks every member before it sends anything, and refuses a group that mixes the two sets, contains a call or a lock, or spans two databases. If the chain fails, the failing member reports the cluster's result code and the others report that they were rolled back.
• Transactions. Atomic groups are the only grouping; isolation levels do not apply.
• Timeouts. A call is bounded by the request's statement timeout and by options.timeout_ms, whichever is shorter. A call that runs out of time returns 503 ConnectionLost. The cluster may or may not have applied a write in that call, so check for the record before retrying the write.

Scaffold

There is nothing to scaffold. The scaffold command stops with a message on a TigerBeetle database, because the service publishes Accounts and Transfers itself, for each service whose database: names the ledger. A configuration can declare the ledger beside other databases, as Several databases in one service describes.