Transactions must be closed by running "commitTransaction" or "rollbackTransaction".
Until you run "commitTransaction", changes made inside the transaction are invisible outside the transaction and are not durably persisted; thus, if the server fails before the transaction commits, all actions in the transaction are automatically rolled back.
- In the "db" API, all commands except session commands can be attached to a transaction. Commands attached to a transaction can insert, update, query, and delete records, and create, alter, and delete databases, tables, and indexes.
- Changes made in a transaction are temporary until they are committed. Thus, queries in different transactions are isolated, which means they cannot see changes made in other transactions until those changes are committed.
- Queries can see pending changes made within their own transaction, and queries can see committed changes from other transactions. This is comparable to the SQL Query Isolation Level of Read Committed.
- Each command always runs in a transaction. When a command is not explicitly attached to a transaction, the server automatically creates a transaction for it, automatically commits it when the command is successful, and automatically rolls it back when the command is unsuccessful.
- Calling the "rollbackTransaction" action rolls back the transaction changes as if they never happened. Rolling back changes is useful when something goes wrong partway through a transaction and you want to undo some or all of the transaction. You can create transaction savepoints and roll back a transaction to any savepoint. This is useful to undo part of a transaction.
- The "createTransaction" action returns a "transactionId" to identify the transaction. Most commands in the "db" API can be run under transaction control by including the "transactionId" property in the "params" object.
Request examples
Maximal
{
"api": "db",
"action": "createTransaction",
"params": {
"transactionDescription": "user-supplied description of a transaction"
},
"responseOptions": {},
"apiVersion": "1.0",
"requestId": "2",
"debug": "max",
"authToken": "replaceWithAuthTokenFromCreateSession"
}Minimal
{
"action": "createTransaction",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Response examples
Minimal
{
"result": {
"transactionId": "transactionId"
},
"errorCode": 0,
"errorMessage": "",
"authToken": "replaceWithAuthTokenFromCreateSession"
}Maximal
{
"authToken": "replaceWithAuthTokenFromCreateSession",
"result": {
"transactionId": "replacedWithATransactionID"
},
"requestId": "00000002",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "db",
"action": "createTransaction",
"requestId": "00000002",
"debug": "max"
},
"serverSuppliedValues": {
"databaseName": null,
"ownerName": null
},
"errorData": {
"errorData": null
},
"warnings": [
]
},
"errorCode": 0,
"errorMessage": ""
}
Request properties ("params")
| Property | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
transactionDescription |
The "transactionDescription" property identifies the object by this description. |
Optional with default of |
string | 0 to 65,500 bytes |
Response properties ("result")
| Property | Description | Type | Limits (inclusive) |
|---|---|---|---|
transactionId |
The |
string | 0 to 255 bytes |