Skip to main content

"createTransaction"

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

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.

Essential information

  • 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

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

Maximal request

{
  "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

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

Failure response

{
  "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'."
}

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

API actionsJSON DB APIjsonActiontransaction actionscreate transactioncreateTransaction

"params"

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

Properties summary

Table 1. "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

transactionDescription

specifies an object for later identification

""

string

0 to 65,500 bytes



"result"

Properties summary

Table 2. "result" properties summary

Property

Description

Type

Limits (inclusive)

transactionId

specifies a server-generated ID that represents a transaction

string

0 to 255 bytes



"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.

Essential information

  • 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.