`"createTransaction"`

Abstract

createTransaction creates a transaction and returns a transactionId value that can be added to other actions to put them under transaction control.

The "createTransaction" action creates a transaction in the session identified by the "authtoken" and returns a "transactionId" value that can be added to other JSON DB API actions to put them under transaction control. You must close a transaction 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.

Things to know

In the "db" API, all commands can be attached to a transaction except for the session commands. Commands attached to a transaction can insert, update, and delete records. They can also create, alter, and delete databases, tables, and indexes. They also can query records.
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’s 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.
Each transaction is represented by a transaction ID. The "createTransaction" action returns a "transactionId" property set to the transaction’s ID. Most commands in the "db" API can be run under transaction control by including the "transactionId" property in the "params" object.

Request examples

Minimal request example

{
  "api": "db",
  "action": "createTransaction",
  "authToken": "replaceWithAuthtokenFromCreateSession"
}

Maximal request example

{
  "api": "db",
  "action": "createTransaction",
  "params": {
    "transactionDescription": "user supplied description of a transaction"
  },
  "responseOptions": {},
  "authToken": "replaceWithAuthtokenFromCreateSession",
  "apiVersion": "1.0",
  "requestId": "2",
  "debug": "max"
}

Response examples

Minimal response example

{
  "authToken": "authtoken",
  "result": {
    "transactionId": "transactionId"
  },
  "errorCode": 0,
  "errorMessage": ""
}

Failure response example

{
  "authToken": "invalidAuthToken",
  "requestId": "2",
  "debugInfo": {
    "request": {
      "authToken": "invalidAuthToken",
      "api": "db",
      "action": "createTransaction",
      "params": {
        "transactionDescription": "user supplied description of a transaction"
      },
      "apiVersion": "1.0",
      "requestId": "2",
      "responseOptions": {},
      "debug": "max"
    }
  },
  "errorCode": 12031,
  "errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}

`"params"`

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

"transactionDescription"

describes an object for later identification

""

string

Minimum length: 0

Maximum length: 65,500

`"result"`

Property summary

Table 2. "result" property summaries

Property

Description

Type

Limits (inclusive)

"transactionId"

contains a server-generated ID that represents a transaction

string

Minimum length: 0

Maximum length: 255

`"transactionId"`

The "transactionId" is an option string that the server generates in order to return during a "createTransaction" action. The generated ID represents a transaction. It defaults to an empty string.

Things to know:

When a client wants an action to be under control of a transaction, it must include the "transactionId" in the action.
A "transactionId" is valid and can be applied to many actions until it is either committed using "commitTransaction" or rolled back using the "rollbackTransaction".
A zero-length string mean the "transactionId" is invalid.
Do not assume that "transactionId" is a number embedded in a string.