Skip to main content

"createTransaction" (JSON Action)

JSON DB "createTransaction" action creates a transaction and returns a transaction ID value that can be added to other actions to put them under transaction control

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

Minimal

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

Maximal

{
  "api": "db",
  "action": "createTransaction",
  "params": {
    "transactionDescription": "user-supplied description of a transaction"
  },
  "responseOptions": {},
  "apiVersion": "1.0",
  "requestId": "2",
  "debug": "max",
  "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": ""
}

Use the createTransaction JSON API action to create a transaction and return a transaction ID value

API actionsJSON DB APIJSON Actiontransaction actionscreate transactioncreateTransaction

"params"

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. createTransaction "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

transactionDescription

(optional) identifies the object by this description.

""

string

0 to 65,500 bytes



"result"

Table 2. createTransaction "result" properties summary

Property

Description

Type

Limits (inclusive)

transactionId

(optional) identifies a server-generated ID that represents a point in the progress of a transaction.

string

0 to 255 bytes



"transactionId"

The "transactionId" is an optional string that the server generates and returns during a "createTransaction" action. The generated ID represents a transaction. In requests, it defaults to an empty string.

  • When a client wants an action to be controlled by a transaction, the "transactionId" must be included in the action request.

  • A "transactionId" is valid and can be applied to multiple actions until it is either committed using "commitTransaction" or rolled back using "rollbackTransaction".

  • A zero-length string means the "transactionId" is invalid.

  • Do not assume that "transactionId" is a number embedded in a string.