OxL Reference
EnglishРусский

11.2 Database transaction

oxl
atomic(db) {
  db.insert(order)
  db.update(User, uid) { ordersCount += 1 }
  emit OrderEvents(OrderEvent.Created(order.id))
}
  • The body is executed in a transaction of the database db. The isolation level is serializable for the built-in storage; for external databases — @isolation(level) or the driver's value.
  • Inside the body only the effect db for this database and emit are allowed. The effects net, io and other databases are a compile error; for net and io the diagnostic code is atomic-db-effects (the effects time and rand do not leave the process and are allowed).

Implementation-defined. Another database in the body (D-8064; D-7790). This implementation cannot tell another database by the effect set: using another database inside atomic(db) is not diagnosed.

  • A serialisation conflict causes an automatic retry of the body up to DB_TX_RETRIES times (a cluster value, 3 by default) within the time budget, then a panic TxConflict. atomic(db) keeps the type of the body and does not add TxConflict to the result type (an edition 1.0 correction: formerly "an error", D-8052; DIV-012; D-7260..D-7262). These values are set in cluster { defaults { db_tx_retries n db_tx_retry_budget d } }; the environment variables OXL_DB_TX_RETRIES and OXL_DB_TX_RETRY_BUDGET_MS override the cluster value (D-8064; D-7780).
  • emit writes the event to the outbox table of the same database; after commit a relay publishes it to the topic (at-least-once).

Implementation-defined. Outbox by database kind (D-8055; DIV-014; D-4999, D-5484). This implementation: the outbox works for builtin:// (including on a node without the local shard leader); for sqlite: and postgres: and for transactions on remote shards emit inside atomic(db) is not supported (an optional feature).

  • In the built-in storage a transaction MUST touch one sharding key; atomic(db, cross_shard: true) permits several shards at the cost of a two-phase commit.

Implementation-defined. Two-phase commit across shards (D-8055; DIV-021; D-4410). An optional feature. This implementation contains no 2PC: the parameter cross_shard: true is accepted with the warning cross-shard-tx, and the body is executed as an ordinary transaction; a request that goes beyond one shard fails at run time with the error CrossShardTx. The warning cross-shard-tx is also issued when find/deleteById of sharded tables in one body use different literal keys; keys that are variables cannot be compared before the run (D-8064; D-7790).

atomic-db-effects, cross-shard-tx

See also

Source: docs/spec/oxl-standard.en.md