Transactions#
Create / interact with Google Cloud Datastore transactions.
-
class
google.cloud.datastore.transaction.
Transaction
(client)[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:>>> from google.cloud import datastore >>> client = datastore.Client() >>> 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
If the transaction block exists 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 = datastore.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 = datastore.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 = datastore.Entity(key=client.key('Thing')) >>> transaction.put(entity) >>> >>> if error: ... transaction.rollback() ... else: ... transaction.commit()
Parameters: client ( google.cloud.datastore.client.Client
) – the client used to connect to datastore.-
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.
-
connection
# Getter for connection over which the batch will run.
Return type: google.cloud.datastore.connection.Connection
Returns: The connection over which the batch will run.
-
current
()[source]# Return the topmost transaction.
Note
If the topmost element on the stack is not a transaction, returns None.
Return type: google.cloud.datastore.transaction.Transaction
or NoneReturns: 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.
-
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 _generated.datastore_pb2.Mutation
protobufs to be sent in the commit request.
-
namespace
# Getter for namespace in which the batch will run.
Return type: str
Returns: The namespace in which the batch will run.
-
project
# Getter for project in which the batch will run.
Return type: str
Returns: The project in which the batch will run.
-
put
(entity)# Remember an entity’s state to be saved during
commit()
.Note
Any existing properties for the entity will be replaced by those currently set on this instance. Already-stored properties which do not correspond to keys set on this instance will be removed from the datastore.
Note
Property values which are “text” (‘unicode’ in Python2, ‘str’ in Python3) map to ‘string_value’ in the datastore; values which are “bytes” (‘str’ in Python2, ‘bytes’ in Python3) map to ‘blob_value’.
When an entity has a partial key, calling
commit()
sends it as aninsert
mutation and the key is completed. On return, the key for theentity
passed in is updated to match the key ID assigned by the server.Parameters: entity ( google.cloud.datastore.entity.Entity
) – the entity to be saved.Raises: ValueError
if the batch is not in progress, if entity has no key assigned, or if the key’sproject
does not match ours.
-