SAVEPOINT
- Couchbase Server 7.0
The SAVEPOINT statement enables you to set a savepoint within a transaction.
Purpose
The SAVEPOINT statement enables you to set a savepoint within an ACID transaction.
Refer to N1QL Support for Couchbase Transactions for further information.
This statement may only be used within a transaction.
If you are using the Query REST API, you must set the txid query parameter to specify the transaction ID.
If you are using the Query Workbench, you don’t need to specify the transaction ID, as long as the statement is part of a multi-statement request. When you start a transaction within a multi-statement request, all statements within the request are assumed to be part of the same transaction until you rollback or commit the transaction.
Similarly, if you are using the cbq shell, you don’t need to specify the transaction ID. 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]
Syntax
savepoint ::= SAVEPOINT savepointname
- savepointname
-
An identifier specifying a name for the savepoint.
If a savepoint with the same name already exists, the existing savepoint is replaced.
Example
If you want to try this example, first refer to Preparation to set up your environment.
BEGIN WORK;
SET TRANSACTION ISOLATION LEVEL READ COMMITTED;
UPSERT INTO test VALUES("abc2", {"a":1});
SAVEPOINT s1; (1)
UPDATE test AS d SET d.b = 10 WHERE d.a > 0; (2)
SELECT d.*, META(d).id FROM test AS d WHERE d.a >= 0;
SAVEPOINT s2; (3)
UPDATE test AS d SET d.b = 10, d.c = "xyz" WHERE d.a > 0; (4)
SELECT d.*, META(d).id FROM test AS d WHERE d.a >= 0;
ROLLBACK TRAN TO SAVEPOINT s2; (5)
SELECT d.*, META(d).id FROM test AS d WHERE d.a >= 0;
COMMIT WORK;| 1 | Set a savepoint. |
| 2 | Update the specified documents in the test keyspace to include a second attribute b. |
| 3 | Set a second savepoint. |
| 4 | Update the specified documents in the test keyspace to include a third attribute named c. |
| 5 | Roll back the transaction to the second savepoint. |
[
{
"_sequence_num": 1,
"_sequence_query": "BEGIN WORK;",
"_sequence_query_status": "success",
"_sequence_result": [
{
"txid": "d9dcc721-321b-42d2-825f-a623eefc28b6"
}
]
},
{
"_sequence_num": 2,
"_sequence_query": "\nUPSERT INTO test VALUES(\"abc2\", {\"a\":1});",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
},
{
"_sequence_num": 3,
"_sequence_query": "\nSAVEPOINT s1;",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
},
{
"_sequence_num": 4,
"_sequence_query": "\nUPDATE test AS d SET d.b = 10 WHERE d.a > 0;",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
},
{
"_sequence_num": 5,
"_sequence_query": "\nSELECT d.*, META(d).id FROM test AS d WHERE d.a >= 0;",
"_sequence_query_status": "success",
"_sequence_result": [
{
"a": 1,
"b": 10, (1)
"id": "abc2"
}
]
},
{
"_sequence_num": 6,
"_sequence_query": "\nSAVEPOINT s2;",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
},
{
"_sequence_num": 7,
"_sequence_query": "\nUPDATE test AS d SET d.b = 10, d.c = \"xyz\" WHERE d.a > 0;",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
},
{
"_sequence_num": 8,
"_sequence_query": "\nSELECT d.*, META(d).id FROM test AS d WHERE d.a >= 0;",
"_sequence_query_status": "success",
"_sequence_result": [
{
"a": 1,
"b": 10,
"c": "xyz", (2)
"id": "abc2"
}
]
},
{
"_sequence_num": 9,
"_sequence_query": "\nROLLBACK TRAN TO SAVEPOINT s2;",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
},
{
"_sequence_num": 10,
"_sequence_query": "\nSELECT d.*, META(d).id FROM test AS d WHERE d.a >= 0;",
"_sequence_query_status": "success",
"_sequence_result": [
{
"a": 1,
"b": 10, (3)
"id": "abc2"
}
]
},
{
"_sequence_num": 11,
"_sequence_query": "\nCOMMIT WORK;",
"_sequence_query_status": "success",
"_sequence_result": {
"results": []
}
}
]| 1 | Before setting the second savepoint, the abc2 document has two attributes: a and b. |
| 2 | After setting the second savepoint and performing an update, the abc2 document has three attributes: a, b, and c. |
| 3 | After rolling back to the second savepoint, the abc2 document again has only two attributes: a and b. |
Related Links
-
For an overview of Couchbase transactions, refer to Transactions.
-
To begin a transaction, refer to BEGIN TRANSACTION.
-
To specify transaction settings, refer to SET TRANSACTION.
-
To rollback a transaction, refer to ROLLBACK TRANSACTION.
-
To commit a transaction, refer to COMMIT TRANSACTION.
-
Blog post: Couchbase Transactions: Elastic, Scalable, and Distributed.