Concurrency and conditional writes¶
TypeDB CE 3.13.6 uses snapshot isolation with optimistic conflict checks at commit. A condition and its writes belong in the same transaction, but that alone does not protect data the transaction only reads. Use the schema's constraints or a deliberate write to the shared record that guards the rule.
The TypeQL examples below run on 3.13.6. They describe server behavior; transaction and query errors still need handling in your chosen driver.
To run these recipes from TypeBridge in Python, TypeScript, Rust or C, see Using TypeBridge transactions. For a whole shopping cart checked and written in one query, see Checkout: a whole cart in one query.
What a transaction sees¶
A transaction opens on a snapshot of committed data. Later commits do not change that snapshot: a read transaction can keep returning the old value after another transaction has changed it. Opening a new transaction gives a new snapshot.
Reads, including match inside a write transaction, are never registered for
conflict validation. There is no read lock or serializable isolation option.
A successful read therefore says nothing about whether another transaction
can change that data before your commit.
Data writers do not acquire blocking locks against each other while their
queries run. TypeDB checks the buffered writes and locks at commit. Among
conflicting concurrent transactions, the first successful committer in the
server's write-ahead-log sequence wins. A later conflicting commit fails
with STC2; all its writes are rejected. A predecessor that aborts does not
win. Schema/write exclusivity is separate: it is acquired at transaction
open and can time out there.
What conflicts¶
TypeDB uses exclusive locks for conflicting writes and unmodifiable locks to prevent concurrent deletion of data a write requires. These are server commit-validation records, not application mutexes. Two unmodifiable locks on the same data are compatible.
| Operation | Commit-time protection and scope |
|---|---|
Write a has edge constrained by @unique |
Exclusive lock for the attribute value within the constraint's owner-type scope. Concurrent owners cannot acquire the same unique value. |
Write a has edge constrained by @key |
The uniqueness lock above plus the ownership cardinality lock; @key combines uniqueness and exactly-one ownership. |
Write/delete a has edge with a checked @card on owns |
Exclusive lock per owner instance and constrained attribute capability. Unordered owns defaults to @card(0..1), so this applies even without an explicit annotation. |
Write/delete a links edge with a checked @card on relates |
Exclusive lock per relation instance and role. Explicit unordered relates defaults to @card(0..1). It does not limit how many different relations a player joins. |
Write/delete a links edge with a checked @card on plays |
Exclusive lock per player instance and role. plays defaults to unbounded @card(0..), which adds no cardinality lock. |
Update ordered has or ordered links |
Exclusive lock on the owner's/relation's order property, so concurrent changes to that ordering conflict. |
| Attach an attribute or role player | Unmodifiable locks on persisted owner/relation/player records; an attribute vertex is protected even when put in this transaction. A concurrent delete of required data conflicts, whichever transaction commits second. |
| Remove the last owner of a non-independent attribute | Cleanup can delete the orphan attribute. A concurrent attachment of that same attribute value elsewhere can therefore conflict with the deletion. |
| Create an entity or relation | Creation itself uses a fresh identifier and takes no shared lock. Adding ownerships or players can add the locks described above. |
| Put an inline attribute value | The put itself has no exclusive lock. A has edge using that value can still take constraint locks. New large-string/struct values also lock their hash bucket; reusing a persisted hashed attribute protects it against deletion. |
Read, or run match without a protected write |
No read lock and no commit validation of the read. Two transactions reading the same rows do not conflict. |
A checked cardinality is any bound other than @card(0..). A bound of two
still takes the same exclusive lock: three concurrent additions to a role
with @card(0..2) can produce one commit and two conflicts, although a second
addition would be legal after retrying. Different player instances do not
share that player-role lock.
Two puts of the same storage key do not by themselves conflict. The constraint and deletion locks above are what matter. A same-value update of a cardinality-constrained ownership still buffers a write and takes its lock; it is not a no-op for conflict detection. A transaction with neither writes nor locks cannot have a data isolation conflict.
These rules follow the 3.13.6 server's commit-lock construction and dependency checks.
Schema and starting data¶
Run this schema in a schema transaction, then commit. The role constraint on
doctor plays assignment:assignee will be used in the assignment recipe.
The doctor ownerships deliberately rely on the default owns @card(0..1).
define
attribute item-id, value string;
attribute stock, value integer;
attribute price, value integer;
attribute account-id, value string;
attribute balance, value integer;
attribute purchase-id, value string;
attribute name, value string;
attribute on-call, value boolean;
attribute version, value integer;
attribute shift-id, value string;
attribute lock-key, value string;
entity item, owns item-id @key, owns stock, owns price, plays purchase:item;
entity account, owns account-id @key, owns balance, plays purchase:buyer;
relation purchase, relates buyer, relates item, owns purchase-id @key;
entity doctor, owns name @key, owns on-call, owns version,
plays assignment:assignee @card(0..1);
entity shift, owns shift-id @key, plays assignment:target;
relation assignment, relates assignee @card(1..1), relates target @card(1..1);
entity lock-row, owns lock-key @key, owns version;
Insert the starting data in a write transaction and commit it. Each recipe starts from this state in its own database; do not run all recipes in sequence on one database without resetting it.
insert
$i isa item, has item-id "item-1", has stock 1, has price 40;
$a isa account, has account-id "account-1", has balance 100;
$d1 isa doctor, has name "doctor-a", has on-call true, has version 0;
$d2 isa doctor, has name "doctor-b", has on-call true, has version 0;
$s1 isa shift, has shift-id "shift-1";
$s2 isa shift, has shift-id "shift-2";
$l isa lock-row, has lock-key "doctor-a-guard", has version 0;
Purchase in one query¶
Put the stock/balance checks, computations and mutations in one write pipeline, then commit the transaction:
match
$i isa item, has item-id "item-1", has stock $s, has price $p;
$s > 0;
$a isa account, has account-id "account-1", has balance $b;
$b >= $p;
let $next-stock = $s - 1;
let $next-balance = $b - $p;
update
$i has stock == $next-stock;
$a has balance == $next-balance;
insert
$purchase isa purchase, links (buyer: $a, item: $i),
has purchase-id "purchase-1";
Computed values in these update assignments require ==; a plain variable
assignment is not the same syntax. If either comparison fails, the match
produces zero rows and the write stages do nothing. A successful commit of
that no-op is a condition failure, not a successful purchase. Inspect the
answer count and the commit result; query success alone is insufficient.
Concurrent buyers of the same item write its stock ownership, and buyers
using the same account write its balance ownership. Those default
cardinality locks prevent overselling and lost balance updates. Two buyers
that both saw the last item can run their queries successfully, but only
one commits; the other receives STC2.
Retry the entire transaction on a fresh snapshot after STC2, with bounded
backoff and jitter. Even with stock for several buyers, contention can let
only one commit per racing round. The price here is the price in the buyer's
snapshot: reading it does not protect it from a concurrent price change.
If the rule requires the price to remain unchanged through commit, include
a same-value write of that ownership in the purchase pipeline as well.
Use one stable purchase ID per logical request; different buyers need different IDs. Keep the same ID when retrying or reconciling that request.
A unique purchase key helps identify an already recorded operation, but it does not turn an unknown commit outcome into a definite failure. Reconcile an unknown outcome using that operation key before applying another charge.
Write skew and a same-value touch¶
Suppose the rule is “at least one of these two doctors must stay on call.” Each transaction reads both on-call doctors:
Transaction A sees two rows and takes doctor A off call:
Transaction B opened before A committed. It also sees two rows and takes doctor B off call:
Both commits succeed: their writes affect different owner instances and the shared reads were never registered. The final state has no doctor on call. This is write skew, even though each transaction was atomic and checked the rule inside its own snapshot.
To make these two operations conflict, both transactions can first touch the same ownerships they rely on, without changing the values:
Run the touch and the chosen doctor's update in the same transaction.
With both doctors touched, one racing commit succeeds and the other gets
STC2; the rejected transaction must start again and re-check the rule.
The touch only protects the records it matches. It does not lock an absent
row, prevent a new matching record, or make arbitrary queries serializable.
When the rule has one stable anchor, a touch of that shared anchor can be more focused. A pre-existing guard row can serve that purpose:
match $l isa lock-row, has lock-key "doctor-a-guard", has version $value;
update $l has version == $value;
Every writer enforcing that rule must touch the same guard row in the transaction that does the protected work. Reading the guard is insufficient.
Use cardinality on plays to serialize assignments¶
The schema above constrains how many assignments each doctor can join. Two transactions can try assigning doctor A to different shifts:
match $d isa doctor, has name "doctor-a";
$s isa shift, has shift-id "shift-1";
insert $a isa assignment, links (assignee: $d, target: $s);
match $d isa doctor, has name "doctor-a";
$s isa shift, has shift-id "shift-2";
insert $a isa assignment, links (assignee: $d, target: $s);
If both transactions opened before either committed, both queries can
succeed, then one commit wins and the other gets STC2. A new transaction
that tries to add another assignment after the winner is visible instead
fails the cardinality check at commit with CNT5.
The constraint belongs on plays for this rule. A relates cardinality
limits players within one assignment relation; separate new assignments
have different relation instances and do not share that lock. Without the
plays constraint, read-check-insert can assign the doctor twice. To limit
assignments per shift instead, constrain the shift's corresponding plays
capability. Higher checked bounds also serialize concurrent additions and
can require retries even when another assignment would fit.
Use keys for uniqueness¶
The purchase relation has a key on purchase-id. Two concurrent
transactions inserting the same key can both pass their query phase, but
only one can commit:
match $i isa item, has item-id "item-1";
$a isa account, has account-id "account-1";
insert $p isa purchase, links (buyer: $a, item: $i),
has purchase-id "purchase-key";
The loser gets STC2 at commit. If the winning key was already visible
when a later transaction opened, the duplicate insert instead fails during
query execution with CNT9 (@unique). Handle both phases. Counting
existing purchases before inserting a different key does not enforce a
limit: that count is only a snapshot read.
An external lock row needs a lease¶
Acquiring a key in one transaction, doing the work in another, and releasing it in a third can coordinate callers that all follow the protocol. For example, acquisition inserts a key and commits:
Release later deletes that row in another committed transaction:
If the holder crashes after acquisition, TypeDB does not expire the row. Every later acquisition sees a uniqueness violation once the key is visible. The rule is blocked until someone deletes the stale row. A safe protocol needs lease expiry, atomic takeover and fencing in the work transaction so an expired holder cannot continue writing. The two snippets above do not implement that protocol.
Inserting and deleting a lock row inside one transaction also does not serialize callers: with no surviving write, there is no protecting lock. A touch of a persistent guard in the work transaction avoids holding a row across transactions and leaves no extra lock behind after a crash or abort.
Commit failures and retries¶
| Failure | What is known | What to do |
|---|---|---|
STC2 isolation conflict |
The transaction definitely did not commit; the server records the abort before returning this error. | Re-run the whole transaction, including reads and conditions, in a new snapshot with bounded backoff. |
CNT9 for an already visible unique key |
The insert was rejected during query execution. | Interpret the key: an existing business operation may already be complete; a lock acquisition may need to wait. Do not blindly repeat an operation with a new key. |
CNT5 for an already exceeded cardinality |
The constraint rejected the transaction. | Re-check the business rule; this is not evidence that a retry can make the same invalid write legal. |
STC1, STC5, STC6, durability-client DUC*, DCT5, or post-commit schema errors such as SCT3/SCT4/SCT5/SCT7 |
Outcome unknown: writes may already be applied, or recovery may apply a pending WAL record. Some schema error codes also occur before commit. | Reconcile the operation's durable result before retrying its effects. A server error response alone does not prove an abort. |
| Transport loss or timeout while committing | Outcome unknown: the server can apply the commit before the connection fails or the response arrives. | Reconcile by a stable operation key. A fresh transaction may inspect committed state; the error itself cannot resolve the outcome. |
After an unknown outcome, an absent result in one fresh snapshot does not prove that an in-flight or recoverable commit will never apply. Preserve the operation key while reconciling; do not turn uncertainty into a second operation with a different key.
A safe retry after STC2 repeats database work, not any external effects
already performed by the application. Keep payment calls, messages and
other irreversible effects out of a transaction retry loop unless they
have their own idempotency protocol.
The 3.13.6 storage commit pipeline can fail while recording an already applied commit's status. Later transaction cleanup can also fail after data or schema commits. These are why an error must not be treated as synonymous with rollback.
Why the conflicting winner is not reported¶
At validation, the server has the predecessor's commit sequence, commit record, conflicting key and lock types. It discards those details when it constructs the isolation error. The conflict enum has only a reason, the protocol carries code/domain/text without winner fields, and the commit response contains no transaction or commit identifier.
Consequently a client cannot report the winning transaction, user, query
or key from STC2. A proxy observing writers can suggest overlapping
candidates, but cannot prove the winner from the error. Reporting a precise
winner requires changes to the server, protocol and driver.
Using TypeBridge transactions¶
A TypeBridge staged transaction runs these recipes from typed plans. Staging
sends nothing; commit opens one TypeDB transaction, runs every staged plan
in order and commits. A failing plan stops the commit and nothing is stored.
Each staged plan's answer resolves only after the commit succeeds.
TypeBridge adds no locks of its own: the rules above apply unchanged, and a
lost race is still STC2, reported as a typed failure.
The purchase as one plan¶
This is the one-query purchase, built from a
generated package's tokens (Item, Item.stock, Purchase.buyer). It is
the program of the writes conformance suite, whose workspace
names the order key order-id:
def purchase(authority: Any) -> Plan:
"""The one-query purchase: take one item and its price, record the order."""
plan = Plan.builder()
item = plan.exact(Item)
buyer = plan.exact(Account)
order_input = plan.input("order_id", "string")
item_input = plan.input("item_id", "string")
account_input = plan.input("account_id", "string")
item_key = plan.field(item, Item.item_id)
buyer_key = plan.field(buyer, Account.account_id)
stock = plan.field(item, Item.stock)
price = plan.field(item, Item.price)
balance = plan.field(buyer, Account.balance)
plan.where_(item_key.eq(item_input)).where_(buyer_key.eq(account_input))
plan.where_(stock.gt(0)).where_(balance.ge(price))
plan.update(item, Item.stock, plan.let_("next_stock", stock - 1))
plan.update(buyer, Account.balance, plan.let_("next_balance", balance - price))
(
plan.insert(Purchase)
.field(Purchase.order_id, order_input)
.player(Purchase.buyer, buyer)
.player(Purchase.item, item)
)
plan.row([order_input.value("O1"), item_input.value("I1"), account_input.value("A1")])
return plan.build(authority)
The where_ conditions and the two let_ values are the match stage, the
two updates one update stage, and the insert the purchase. Each input
column takes one value per given row. Python spells where_ and let_ to
avoid its keywords.
The other SDKs build the same plan bytes; the conformance suite compares them byte for byte, directly and over the proxy:
/** The one-query purchase: take one item and its price, record the order. */
function purchase(authority: QueryV2Authority): Built {
const plan = Plan.builder();
const item = plan.exact(Item);
const buyer = plan.exact(Account);
const orderInput = plan.input("order_id", "string");
const itemInput = plan.input("item_id", "string");
const accountInput = plan.input("account_id", "string");
const itemKey = plan.field(item, Item.fields.itemId);
const buyerKey = plan.field(buyer, Account.fields.accountId);
const stock = plan.field(item, Item.fields.stock);
const price = plan.field(item, Item.fields.price);
const balance = plan.field(buyer, Account.fields.balance);
plan
.where(itemKey.eq(itemInput))
.where(buyerKey.eq(accountInput))
.where(stock.gt(0n))
.where(balance.ge(price));
plan.update(item, Item.fields.stock, plan.let("next_stock", stock.sub(1n)));
plan.update(buyer, Account.fields.balance, plan.let("next_balance", balance.sub(price)));
plan
.insert(Purchase)
.field(Purchase.fields.orderId, orderInput)
.player(Purchase.roles.buyer, buyer)
.player(Purchase.roles.item, item);
plan.row([orderInput.value("O1"), itemInput.value("I1"), accountInput.value("A1")]);
return plan.build(authority);
}
/// The one-query purchase: take one item and its price, record the order.
fn purchase() -> Result<Built> {
let mut plan = Plan::builder();
let item = plan.exact::<Item>();
let buyer = plan.exact::<Account>();
let order_input = plan.input::<String>("order_id");
let item_input = plan.input::<String>("item_id");
let account_input = plan.input::<String>("account_id");
let item_key = plan.field(item, ItemType::item_id);
let buyer_key = plan.field(buyer, AccountType::account_id);
let stock = plan.field(item, ItemType::stock);
let price = plan.field(item, ItemType::price);
let balance = plan.field(buyer, AccountType::balance);
plan.where_(item_key.eq(item_input))
.where_(buyer_key.eq(account_input))
.where_(stock.gt(0_i64))
.where_(balance.ge(price));
let next_stock = plan.let_("next_stock", stock - 1_i64);
let next_balance = plan.let_("next_balance", balance - price);
plan.update(item, ItemType::stock, next_stock).update(
buyer,
AccountType::balance,
next_balance,
);
plan.insert::<Purchase>()
.field(PurchaseType::order_id, order_input)
.player(PurchaseType::buyer, buyer)
.player(PurchaseType::item, item);
plan.row([
order_input.value("O1".to_owned()),
item_input.value("I1".to_owned()),
account_input.value("A1".to_owned()),
]);
plan.build(&models::SCHEMA)
}
/* The one-query purchase: take one item and its price, record the order. */
static type_bridge_status_t purchase(type_bridge_plan_builder_t *plan, const identities_t *id) {
type_bridge_status_t status;
uint32_t item, buyer, order_input, item_input, account_input;
uint32_t item_key, buyer_key, stock, price, balance;
uint32_t zero, one, stock_expr, balance_expr, next_stock, next_balance, order;
uint32_t row[3];
CHECK(type_bridge_plan_builder_exact(plan, id->item, &item));
CHECK(type_bridge_plan_builder_exact(plan, id->account, &buyer));
CHECK(input(plan, "order_id", TYPE_BRIDGE_PROJECTED_VALUE_STRING, &order_input));
CHECK(input(plan, "item_id", TYPE_BRIDGE_PROJECTED_VALUE_STRING, &item_input));
CHECK(input(plan, "account_id", TYPE_BRIDGE_PROJECTED_VALUE_STRING, &account_input));
CHECK(type_bridge_plan_builder_field(plan, item, id->item_id, &item_key));
CHECK(type_bridge_plan_builder_field(plan, buyer, id->account_id, &buyer_key));
CHECK(type_bridge_plan_builder_field(plan, item, id->stock, &stock));
CHECK(type_bridge_plan_builder_field(plan, item, id->price, &price));
CHECK(type_bridge_plan_builder_field(plan, buyer, id->balance, &balance));
CHECK(type_bridge_plan_builder_value_long(plan, 0, &zero));
CHECK(type_bridge_plan_builder_value_long(plan, 1, &one));
CHECK(type_bridge_plan_builder_compare(plan, TYPE_BRIDGE_PLAN_OPERAND_BINDING, item_key,
TYPE_BRIDGE_PLAN_COMPARE_EQUAL,
TYPE_BRIDGE_PLAN_OPERAND_INPUT, item_input));
CHECK(type_bridge_plan_builder_compare(plan, TYPE_BRIDGE_PLAN_OPERAND_BINDING, buyer_key,
TYPE_BRIDGE_PLAN_COMPARE_EQUAL,
TYPE_BRIDGE_PLAN_OPERAND_INPUT, account_input));
CHECK(type_bridge_plan_builder_compare(plan, TYPE_BRIDGE_PLAN_OPERAND_BINDING, stock,
TYPE_BRIDGE_PLAN_COMPARE_GREATER,
TYPE_BRIDGE_PLAN_OPERAND_VALUE, zero));
CHECK(type_bridge_plan_builder_compare(plan, TYPE_BRIDGE_PLAN_OPERAND_BINDING, balance,
TYPE_BRIDGE_PLAN_COMPARE_GREATER_OR_EQUAL,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, price));
CHECK(type_bridge_plan_builder_expr_arith(plan, TYPE_BRIDGE_PLAN_ARITH_SUB,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, stock,
TYPE_BRIDGE_PLAN_OPERAND_VALUE, one, &stock_expr));
CHECK(type_bridge_plan_builder_let(plan, view("next_stock"), TYPE_BRIDGE_PLAN_OPERAND_EXPR,
stock_expr, &next_stock));
CHECK(type_bridge_plan_builder_update(plan, item, id->stock, TYPE_BRIDGE_PLAN_OPERAND_BINDING,
next_stock));
CHECK(type_bridge_plan_builder_expr_arith(plan, TYPE_BRIDGE_PLAN_ARITH_SUB,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, balance,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, price,
&balance_expr));
CHECK(type_bridge_plan_builder_let(plan, view("next_balance"), TYPE_BRIDGE_PLAN_OPERAND_EXPR,
balance_expr, &next_balance));
CHECK(type_bridge_plan_builder_update(plan, buyer, id->balance,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, next_balance));
CHECK(type_bridge_plan_builder_insert(plan, id->purchase, &order));
CHECK(type_bridge_plan_builder_thing_field(plan, order, id->order_id,
TYPE_BRIDGE_PLAN_OPERAND_INPUT, order_input));
CHECK(type_bridge_plan_builder_thing_player(plan, order, id->buyer, buyer));
CHECK(type_bridge_plan_builder_thing_player(plan, order, id->item_role, item));
CHECK(type_bridge_plan_builder_value_string(plan, view("O1"), &row[0]));
CHECK(type_bridge_plan_builder_value_string(plan, view("I1"), &row[1]));
CHECK(type_bridge_plan_builder_value_string(plan, view("A1"), &row[2]));
CHECK(type_bridge_plan_builder_row(plan, row, 3u));
done:
return status;
}
Commit, and retry a conflict¶
def buy(db: Database, plan: Plan, *, attempts: int = 5) -> bool:
"""Commit the purchase; True when it bought, False when a condition failed."""
for attempt in range(attempts):
try:
with db.staged_transaction("write") as tx:
bought = tx.stage(plan) # nothing is sent yet
# Committed on exit. Zero matched rows: out of stock or short of
# funds, and nothing was written.
return bought.result() == Matched(1)
except CommitConflict:
# Another buyer committed first and nothing was stored. Run the
# whole plan again on a fresh snapshot, after a jittered backoff.
if attempt + 1 == attempts:
raise
time.sleep(random.uniform(0, 0.01 * 2**attempt))
raise ValueError("attempts must be at least 1")
As a with block, db.staged_transaction("write") commits on a clean exit,
discards on an exception, and closes. Matched(0) is the failed condition
described above: the commit succeeded and wrote nothing.
Typed failures¶
A failed commit raises one of three classes from type_bridge. Each carries
.failure, a value-free Failure: phase, reason, lock_kind,
annotation, op_index (the failing staged plan), retry_safe and the
provider code. Values and the conflicting winner are
never included.
| Class | failure |
What to do |
|---|---|---|
CommitConflict |
reason conflict, code STC2, with lock_kind |
Nothing was stored. Run the whole transaction again on a fresh snapshot. |
CommitRejected (the base of CommitConflict) |
reason cardinality (CNT5), unique (CNT9), constraint or other |
Nothing was stored. Re-check the rule; the same write fails again. |
CommitOutcomeUnknown |
code such as STC1, DCT5 or none; retry_safe false |
The writes may have applied. Reconcile by the operation key before repeating them. |
failure.retry_safe is true for every proven rejection: repeating the whole
transaction cannot apply it twice. It does not promise that a repeat
succeeds; only a conflict can change on a new snapshot. A rejection while a
plan runs, before commit (phase query, such as CNT9 for an already
visible key), is not one of these classes, but it carries the same
.failure.
An unknown outcome over the proxy¶
Over the TypeBridge proxy, each commit is one signed query-remote/v3
request. The proxy keeps no replies, so a reply lost on the way back or one
that cannot be verified is commit_outcome_unknown, as a lost direct commit
is. The purchase may have applied: read the database by the order key before
buying again.
def buy_over_proxy(proxy: ProxyConnection, plan: Plan, placed: Plan) -> bool:
"""Commit once over the proxy; after a lost reply, read whether it applied."""
tx = proxy.transaction("write")
try:
bought = tx.stage(plan)
try:
tx.commit()
except Exception as error:
if getattr(error, "code", None) != "commit_outcome_unknown":
raise
# The reply was lost and the purchase may have applied: the
# database decides, by whether the order now exists.
with proxy.transaction("read") as check:
found = check.stage(placed)
return found.result() == Exists(True)
return bought.result() == Matched(1)
finally:
tx.close()
The server never runs the same request twice. It holds each request's nonce for the request's lifetime and refuses the same bytes again; a write refused that way also reads as unknown, because the first copy may have committed. Every other signed refusal applied nothing. When and how to retry, and how many transactions run at once, is the application's policy.
The same names in each SDK¶
| Python | TypeScript | Rust | C (ABI 1.7) | |
|---|---|---|---|---|
| Plan builder | type_bridge.plan.Plan.builder() |
Plan.builder() |
type_bridge::plan::Plan::builder() |
type_bridge_plan_builder_new, type_bridge_plan_builder_* |
| Direct transaction | db.staged_transaction("write") |
db.stagedTransaction("write") |
db.transaction(TransactionOptions::default().with_kind(TransactionKind::Write)) |
type_bridge_database_transaction(db, TYPE_BRIDGE_TRANSACTION_WRITE, ...) |
| Proxy transaction | proxy.transaction("write"), proxy from the generated package's connect_proxy(url) |
await proxy.transaction("write"), proxy from the generated package's await connectProxy(url) |
proxy.transaction(options).await, proxy from ProxyDatabase::connect |
type_bridge_proxy_connection_transaction |
| Stage, commit | tx.stage(plan), tx.commit() |
tx.stage(plan), await tx.commit() |
tx.stage(&plan), tx.commit().await |
type_bridge_staged_transaction_stage, type_bridge_staged_transaction_commit |
| Answer | pending.result() |
pending.get() |
pending.get() |
type_bridge_pending_answer |
| Typed failure | error.failure |
QueryV2Error.failure (ProviderFailure) |
CommitError.failure (type_bridge::failure::Failure) |
type_bridge_execution_diagnostics_failure_get_v1 |
| Conflict | CommitConflict |
failure.reason === "conflict" |
Failure::Rejected { reason: Reason::Conflict { .. }, .. } |
reason == TYPE_BRIDGE_FAILURE_REASON_CONFLICT |
| Retry safe | failure.retry_safe |
failure.retry_safe |
failure.retry_safe() |
failure.retry_safe |
| Unknown outcome | CommitOutcomeUnknown; over the proxy error.code == "commit_outcome_unknown" |
error.code === "commit_outcome_unknown" |
error.diagnostic().code().as_str() == "commit_outcome_unknown" |
TYPE_BRIDGE_STATUS_COMMIT_OUTCOME_UNKNOWN |
| Discard, keep the transaction | tx.rollback() |
tx.rollback() |
tx.rollback() |
type_bridge_staged_transaction_rollback(tx) |
| Release | tx.close() |
tx.close() |
tx.close() |
type_bridge_staged_transaction_close(&tx) |