A transaction is a set of operations on one or more entities. Each transaction is guaranteed to be atomic, meaning that transactions are never partially applied. Either all of the operations in the transaction are applied, or none of them are applied.
Using transactions
Transactions have a maximum duration of 60 seconds with a 10 second idle expiration time after 30 seconds.
An operation may fail when:
- Too many concurrent modifications are attempted on the same entity.
- The transaction exceeds a resource limit.
- The Datastore mode database encounters an internal error.
In all these cases, the Cloud Datastore API returns an error.
Transactions are an optional feature. You're not required to use transactions to perform database operations.
An application can execute a set of statements and operations in a single transaction, such that if any statement or operation raises an exception, none of the database operations in the set are applied. The application defines the actions to perform in the transaction.
The following snippet shows how to perform a transaction. It transfers money from one account to another.
C#
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore C# API reference documentation .
Go
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Go API reference documentation .
Java
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Java API reference documentation .
Node.js
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Node.js API reference documentation .
PHP
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore PHP API reference documentation .
Python
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Python API reference documentation .
Ruby
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Ruby API reference documentation .
Note that in order to keep our examples more succinct we sometimes omit the rollback
if the transaction fails. In production code, it is important to ensure that every transaction is either explicitly committed or rolled back.
What can be done in a transaction
Transactions can query or lookup any number of entities. You can create, update, or delete up to 500 entities in each transaction. The maximum size of a transaction is 10 MiB.
Isolation and consistency
Serializable isolation is enforced in Datastore mode databases. This means that data read or modified by a transaction cannot be concurrently modified. For more information on isolation levels, read the Serializable Isolation and Transaction Isolation articles.
Queries and lookups in a transaction see a consistent snapshot of the state of the database. This snapshot is guaranteed to contain the effect of all transactions and writes that completed prior to the beginning of the transaction.
This consistent snapshot view also extends to reads after writes inside transactions. Unlike with most databases, queries and lookups inside a Datastore mode transaction do not see the results of previous writes inside that transaction. Specifically, if an entity is modified or deleted within a transaction, a query or lookup returns the original version of the entity as of the beginning of the transaction, or nothing if the entity did not exist then.
Outside of transactions, queries and lookups also have serializable isolation.
Uses for transactions
One use of transactions is updating an entity with a new property value relative
to its current value. The transferFunds
example above does that for two
entities, by withdrawing money from one account and transferring it to another.
The Cloud Datastore API does not automatically retry transactions, but you
can add your own logic to retry them, for instance to handle conflicts when
another request updates the same entity at the same time.
C#
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore C# API reference documentation .
Go
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Go API reference documentation .
Java
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Java API reference documentation .
Node.js
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Node.js API reference documentation .
PHP
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore PHP API reference documentation .
Python
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Python API reference documentation .
Ruby
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Ruby API reference documentation .
This requires a transaction because the value of balance
in an entity may be updated by another user after this code fetches the object, but before it saves the modified object. Without a transaction, the user's request uses the value of balance
prior to the other user's update, and the save overwrites the new value. With a
transaction, the application is told about the other user's update.
Another common use for transactions is to fetch an entity with a named key, or create it if it doesn't yet exist (this example builds on the TaskList example from creating an entity):
C#
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore C# API reference documentation .
Go
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Go API reference documentation .
Java
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Java API reference documentation .
Node.js
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Node.js API reference documentation .
PHP
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore PHP API reference documentation .
Python
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Python API reference documentation .
Ruby
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Ruby API reference documentation .
As before, a transaction is necessary to handle the case where another user is attempting to create or update an entity with the same string ID. Without a transaction, if the entity does not exist and two users attempt to create it, the second overwrites the first without knowing that it happened.
When a transaction fails, you can have your app retry the transaction until it succeeds, or you can let your users deal with the error by propagating it to your app's user interface level. You do not have to create a retry loop around every transaction.
Read-only transactions
Finally, you can use a transaction to read a consistent snapshot of the database. This can be useful when you need multiple reads to render a page or to export data that must be consistent. You can create read-only transaction for these cases.
Read-only transactions cannot modify entities, but in return, they do not contend with any other transactions and do not need to be retried. If you perform only reads in a regular, read-write transaction, then that transaction may contend with transaction that modify the same data.
C#
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore C# API reference documentation .
Go
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Go API reference documentation .
Java
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Java API reference documentation .
Node.js
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Node.js API reference documentation .
PHP
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore PHP API reference documentation .
Python
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Python API reference documentation .
Ruby
To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries . For more information, see the Cloud Datastore Ruby API reference documentation .
What's next
- Learn about Queries.