Native single-database transactions

Availability

This describes the native single-database contract being qualified for production. It is not a claim that native access has been enabled for your project. Admission requires a compatible runtime and managed compiler/SDK, a sole DEFAULT, verified primary/schema readiness and explicit database policy grants. Existing read-only imports do not gain write permission automatically.

Atomic work and concurrent editors

A transaction submits one bounded batch to the Turso primary. Business changes and the operation receipt commit together. If a statement, constraint or affected-row assertion fails, the whole attempted batch rolls back. Do not hold a transaction open for user input, HTTP requests or an upload scan.

For editing, store a version with each document. Update using the version the user read:

UPDATE documents
SET body = ?, version = version + 1
WHERE id = ? AND version = ?

Require expect_affected_rows: 1. A competing edit changes the version, so a stale edit fails instead of silently overwriting it. Read the current primary value and let the application or user resolve the conflict. Do not automatically substitute a new version into the old request. Use unique constraints, foreign keys and atomic SQL updates for other business invariants.

Persist an intent before writing

Obtain database_id and generation from a successful primary read. Persist that scope, a fresh operation ID and the exact statements and parameters before the first mutation. Keep them across retries, page refreshes and region changes. The expected scope is mandatory for writes and status requests.

Result	Meaning and recovery
committed	A primary receipt proves commitment. A missing result body or failed replica refresh does not authorize a new write.
not_committed	The current attempt was rejected with confirmed rollback. Inspect the error; conflicting reuse of an ID is not permission to replace a different earlier operation.
unknown	The response cannot establish the outcome. Retain the original identity and payload; query status or retry that exact request.

Receipt absence is reported as unknown, not as proof that an earlier request failed. Matching retries within the same database generation recover the receipt before executing business SQL. Reusing an ID with changed SQL or parameters is rejected. Full result bodies have limited retention; compact receipts remain for the generation lifetime. A restore can rewind receipts and requires separate reconciliation before replaying old operations.

Reads across regions

primary is the default. session also goes to the primary and checks the referenced operation receipt, including after moving to another edge. eventual may use a healthy local read replica, otherwise it falls back to the primary. Preview currently uses primary fallback.

Each edge pulls replication changes independently. A successful recent pull is not a guarantee that the replica includes the latest concurrent write. Use primary/session reads for permissions, balances, inventory and immediate post-write views. During a partition, strong operations can fail instead of serving stale data or accepting local writes.

Boundaries

Only one database participates. Cross-database and long-lived interactive transactions are unsupported. SQL administration, attached databases, extensions and explicit transaction-control SQL are denied. Hosted schema admission can reject views, triggers, virtual tables and unsupported stored expressions; the platform does not silently remove them.

Use a durable application outbox and provider idempotency for external side effects. For attachments, track upload, adoption and cleanup states and reconcile uncertain database outcomes before deleting a candidate object. Neither HTTP nor object storage becomes part of the SQL commit.