Transactions#
Create / interact with Google Cloud Datastore transactions.
-
class
google.cloud.datastore.transaction.
Transaction
(client, read_only=False)[source]# Bases:
google.cloud.datastore.batch.Batch
An abstraction representing datastore Transactions.
Transactions can be used to build up a bulk mutation and ensure all or none succeed (transactionally).
For example, the following snippet of code will put the two
save
operations (eitherinsert
orupsert
) into the same mutation, and execute those within a transaction:>>> with client.transaction(): ... client.put_multi([entity1, entity2])
Because it derives from
Batch
,Transaction
also providesput()
anddelete()
methods:>>> with client.transaction() as xact: ... xact.put(entity1) ... xact.delete(entity2.key)
By default, the transaction is rolled back if the transaction block exits with an error:
>>> with client.transaction(): ... do_some_work() ... raise SomeException # rolls back Traceback (most recent call last): ... SomeException
If the transaction block exits without an exception, it will commit by default.
Warning
Inside a transaction, automatically assigned IDs for entities will not be available at save time! That means, if you try:
>>> with client.transaction(): ... entity = Entity(key=client.key('Thing')) ... client.put(entity)
entity
won’t have a complete key until the transaction is committed.Once you exit the transaction (or call
commit()
), the automatically generated ID will be assigned to the entity:>>> with client.transaction(): ... entity = Entity(key=client.key('Thing')) ... client.put(entity) ... print(entity.key.is_partial) # There is no ID on this key. ... True >>> print(entity.key.is_partial) # There *is* an ID. False
If you don’t want to use the context manager you can initialize a transaction manually:
>>> transaction = client.transaction() >>> transaction.begin() >>> >>> entity = Entity(key=client.key('Thing')) >>> transaction.put(entity) >>> >>> transaction.commit()
- Parameters
client (
google.cloud.datastore.client.Client
) – the client used to connect to datastore.read_only (bool) – indicates the transaction is read only.
-
begin
()[source]# Begins a transaction.
This method is called automatically when entering a with statement, however it can be called explicitly if you don’t want to use a context manager.
- Raises
ValueError
if the transaction has already begun.
-
commit
()[source]# Commits the transaction.
This is called automatically upon exiting a with statement, however it can be called explicitly if you don’t want to use a context manager.
This method has necessary side-effects:
Sets the current transaction’s ID to None.
-
current
()[source]# Return the topmost transaction.
Note
If the topmost element on the stack is not a transaction, returns None.
- Return type
- Returns
The current transaction (if any are active).
-
delete
(key)# Remember a key to be deleted during
commit()
.- Parameters
key (
google.cloud.datastore.key.Key
) – the key to be deleted.- Raises
ValueError
if the batch is not in progress, if key is not complete, or if the key’sproject
does not match ours.
-
property
id
# Getter for the transaction ID.
- Return type
- Returns
The ID of the current transaction.
-
property
mutations
# Getter for the changes accumulated by this batch.
Every batch is committed with a single commit request containing all the work to be done as mutations. Inside a batch, calling
put()
with an entity, ordelete()
with a key, builds up the request by adding a new mutation. This getter returns the protobuf that has been built-up so far.- Return type
iterable
- Returns
The list of
datastore_pb2.Mutation
protobufs to be sent in the commit request.
-
property
namespace
# Getter for namespace in which the batch will run.
- Return type
- Returns
The namespace in which the batch will run.
-
property
project
# Getter for project in which the batch will run.
- Return type
- Returns
The project in which the batch will run.
-
put
(entity)[source]# Adds an entity to be committed.
Ensures the transaction is not marked readonly. Please see documentation at
put()
- Parameters
entity (
Entity
) – the entity to be saved.- Raises
RuntimeError
if the transaction is marked ReadOnly