You are viewing the documentation for a prerelease version.

BEGIN TRANSACTION

  • Couchbase Server 7.0
    +
    The BEGIN TRANSACTION statement enables you to begin a transaction.

    Purpose

    The BEGIN TRANSACTION statement enables you to begin a sequence of statements as an ACID transaction. Refer to Transactions for further information.

    • Only DML statements are permitted within a transaction: INSERT, UPSERT, DELETE, UPDATE, MERGE, SELECT, EXECUTE FUNCTION, PREPARE, or EXECUTE.

    • The EXECUTE FUNCTION statement is only permitted in a transaction if the user-defined function does not contain any subqueries other than SELECT subqueries.

    • The PREPARE and EXECUTE statements are only permitted in a transaction for the DML statements listed above.

    All statements within a transaction are sent to the same Query node.

    You can also specify a single DML statement as an ACID transaction by setting the tximplicit query parameter.

    Syntax

    begin-transaction ::= ( BEGIN | START ) ( WORK | TRAN | TRANSACTION ) [ ISOLATION LEVEL READ COMMITTED ]
    ( 'BEGIN' | 'START' ) ( 'WORK' | 'TRAN' | 'TRANSACTION' ) ( 'ISOLATION' 'LEVEL' 'READ' 'COMMITTED' )?

    The BEGIN and START keywords are synonyms. The statement must begin with one of these keywords.

    The WORK, TRAN, and TRANSACTION keywords are synonyms. The statement must contain one of these keywords.

    Transaction Settings

    Currently, the only available transaction setting is "isolation level read committed". This setting is enabled by default. The ISOLATION LEVEL READ COMMITTED keywords are therefore optional and may be omitted.

    Return Value

    The statement returns an object containing the following property.

    txid

    The transaction ID.

    If you are using the Query Workbench or the Query REST API, you must set the txid query parameter to specify the transaction ID for any subsequent statements that form part of the same transaction.

    If you are using the cbq shell, you don’t need to specify the transaction ID for any subsequent statements that form a part of the same transaction. Once you have started a transaction, all statements within the cbq shell session are assumed to be part of the same transaction until you rollback or commit the transaction. [1]

    Examples

    Example 1. Begin a transaction with default parameters
    Request
    START TRANSACTION;
    Result
    [
        {
            "txid": "d81d9b4a-b758-4f98-b007-87ba262d3a51" (1)
        }
    ]
    1 The transaction ID. If you are using the Query Workbench or the Query REST API, you must use this ID to add further statements to the transaction.
    Example 2. Begin a transaction and set parameters — cbq shell
    Request
    cbq> \SET -txtimeout "2m"; (1)
    cbq> \SET -scan_consistency "request_plus"; (2)
    cbq> \SET -durability_level "majority"; (3)
    cbq> START TRANSACTION;
    1 The transaction timeout.
    2 The transaction scan consistency. No scan consistency is set for individual statements within the transaction; they inherit from the transaction scan consistency.
    3 Durability level of all the mutations within the transaction.
    Example 3. A statement participating in the transaction — cbq shell
    Request
    cbq> SELECT ...;

    You do not need to specify the transaction ID within the same cbq shell session.

    Example 4. Begin a transaction and set parameters — REST API
    CURL request
    $ curl http://localhost:8093/query/service \
    -u Administrator:password \
    -H 'Content-Type: application/json' \
    -d '{
      "statement": "START TRANSACTION",
      "pretty": true,
      "txtimeout": "2m",
      "scan_consistency": "request_plus",
      "durability_level": "majority"
    }'

    This is equivalent to the request in Example 2.

    Example 5. A statement participating in the transaction — REST API
    CURL request
    $ curl http://localhost:8093/query/service \
    -u Administrator:password \
    -H 'Content-Type: application/json' \
    -d '{
      "statement": "SELECT ...",
      "pretty": true,
      "txid": "d81d9b4a-b758-4f98-b007-87ba262d3a51" (1)
    }'

    This is equivalent to the request in Example 3.

    1 The transaction ID generated when the transaction began.

    1. You must be using cbq shell version 2.0 or above to use the automatic transaction ID functionality.