Transazioni

Nota: gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, come la memorizzazione nella cache automatica delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client DB precedente, leggi la Guida alla migrazione dal database a NDB

Datastore supporta le transazioni. Una transazione è un'operazione o un insieme di operazioni atomico: tutte le operazioni nella transazione si verificano o non si verificano nessuna di queste. Un'applicazione può eseguire più operazioni e calcoli in una singola transazione.

Utilizzo delle transazioni

Una transazione è un insieme di operazioni Datastore su una o più entità. Ogni transazione è garantita per essere atomica, il che significa che le transazioni non vengono mai applicate parzialmente. Vengono applicate tutte le operazioni nella transazione o nessuna di queste viene applicata. Le transazioni hanno una durata massima di 60 secondi con una scadenza di inattività di 10 secondi dopo 30 secondi.

Un'operazione potrebbe non riuscire se:

• Vengono tentate troppe modifiche simultanee allo stesso gruppo di entità.
• La transazione supera il limite di risorse.
• Datastore rileva un errore interno.

In tutti questi casi, l'API Datastore genera un'eccezione.

Nota: se l'applicazione riceve un'eccezione quando esegui il commit di una transazione, non significa sempre che la transazione non sia andata a buon fine. Puoi ricevere eccezioni Timeout, TransactionFailedError o InternalError nei casi in cui è stato eseguito il commit delle transazioni e alla fine verranno applicate correttamente. Quando possibile, rendi idempotenti le transazioni Datastore in modo che, se si ripete una transazione, il risultato finale sarà lo stesso.

Le transazioni sono una funzionalità facoltativa di Datastore; non è necessario utilizzare le transazioni per eseguire le operazioni di Datastore.

Un'applicazione può eseguire un insieme di istruzioni e operazioni di datastore in una singola transazione, in modo che, se una qualsiasi istruzione o operazione genera un'eccezione, non viene applicata nessuna delle operazioni Datastore nel set. L'applicazione definisce le azioni da eseguire nella transazione utilizzando una funzione Python. L'applicazione avvia la transazione utilizzando uno dei metodi run_in_transaction, a seconda che la transazione acceda alle entità all'interno di un singolo gruppo di entità o che si tratti di una transazione tra gruppi.

Per il caso d'uso comune di una funzione utilizzata solo nelle transazioni, utilizza il decorator @db.transactional:

from google.appengine.ext import db

class Accumulator(db.Model):
    counter = db.IntegerProperty(default=0)

@db.transactional
def increment_counter(key, amount):
    obj = db.get(key)
    obj.counter += amount
    obj.put()

q = db.GqlQuery("SELECT * FROM Accumulator")
acc = q.get()

increment_counter(acc.key(), 5)

Se a volte la funzione viene chiamata senza una transazione, invece di decorarla, chiama db.run_in_transaction() con la funzione come argomento:

from google.appengine.ext import db

class Accumulator(db.Model):
    counter = db.IntegerProperty(default=0)

def increment_counter(key, amount):
    obj = db.get(key)
    obj.counter += amount
    obj.put()

q = db.GqlQuery("SELECT * FROM Accumulator")
acc = q.get()

db.run_in_transaction(increment_counter, acc.key(), 5)

db.run_in_transaction() prende l'oggetto della funzione e gli argomenti posizionali e delle parole chiave da passare alla funzione. Se la funzione restituisce un valore, db.run_in_transaction() restituisce quel valore.

Se la funzione restituisce, viene eseguito il commit della transazione e vengono applicati tutti gli effetti delle operazioni del datastore. Se la funzione genera un'eccezione, viene eseguito il rollback della transazione e gli effetti non vengono applicati. Vedi la nota precedente sulle eccezioni.

Quando una funzione di transazione viene chiamata dall'interno di un'altra transazione, @db.transactional e db.run_in_transaction() hanno un comportamento predefinito diverso. @db.transactional lo consentirà e la transazione interna diventerà la stessa della transazione esterna. La chiamata a db.run_in_transaction() tenta di "nidificare" un'altra transazione all'interno della transazione esistente; tuttavia, questo comportamento non è ancora supportato e genera db.BadRequestError. Puoi specificare un altro comportamento; consulta il riferimento delle funzioni nelle opzioni di transazione per maggiori dettagli.

Utilizzare transazioni in più gruppi (XG)

Le transazioni in più gruppi, che operano su più gruppi di entità, si comportano come transazioni di un gruppo singolo, ma non generano errori se il codice cerca di aggiornare le entità da più gruppi di entità. Per richiamare una transazione tra gruppi, usa le opzioni di transazione.

In uso: @db.transactional:

from google.appengine.ext import db

@db.transactional(xg=True)
def make_things():
  thing1 = Thing(a=3)
  thing1.put()
  thing2 = Thing(a=7)
  thing2.put()

make_things()

In uso: db.run_in_transaction_options:

from google.appengine.ext import db

xg_on = db.create_transaction_options(xg=True)

def my_txn():
    x = MyModel(a=3)
    x.put()
    y = MyModel(a=7)
    y.put()

db.run_in_transaction_options(xg_on, my_txn)

Che cosa può essere fatto in una transazione

Datastore impone limitazioni sulle operazioni che possono essere eseguite all'interno di una singola transazione.

Tutte le operazioni Datastore in una transazione devono operare su entità nello stesso gruppo di entità se si tratta di una transazione a gruppo singolo o su entità in un massimo di venticinque gruppi di entità se si tratta di una transazione tra gruppi. Ciò include query sulle entità per predecessore, recupero di entità per chiave, aggiornamento delle entità ed eliminazione di entità. Tieni presente che ogni entità base appartiene a un gruppo di entità separato, quindi una singola transazione non può creare o operare su più di un'entità base, a meno che non si tratti di una transazione tra gruppi.

Quando due o più transazioni tentano contemporaneamente di modificare le entità in uno o più gruppi di entità comuni, solo la prima transazione per eseguire il commit delle modifiche può andare a buon fine, mentre tutte le altre non andranno a buon fine con il commit. Grazie a questa struttura, l'utilizzo di gruppi di entità limita il numero di scritture simultanee che puoi eseguire su qualsiasi entità dei gruppi. Quando viene avviata una transazione, Datastore utilizza il controllo ottimistico della contemporaneità controllando l'ora dell'ultimo aggiornamento dei gruppi di entità utilizzati nella transazione. Dopo aver eseguito il commit di una transazione per i gruppi di entità, Datastore controlla di nuovo l'ora dell'ultimo aggiornamento per i gruppi di entità utilizzati nella transazione. Se è cambiata dal controllo iniziale, viene generata un'eccezione.

Un'app può eseguire una query durante una transazione, ma solo se include un filtro dei predecessori. Un'app può recuperare le entità Datastore anche per chiave durante una transazione. Puoi preparare le chiavi prima della transazione oppure puoi creare chiavi all'interno della transazione utilizzando ID o nomi delle chiavi.

Tutto il codice Python è consentito all'interno di una funzione Transaction. Puoi determinare se l'ambito attuale è nidificato in una funzione Transaction utilizzando db.is_in_transaction(). La funzione Transaction non deve avere effetti collaterali diversi dalle operazioni del datastore. La funzione Transaction può essere chiamata più volte se un'operazione di Datastore non riesce a causa di un altro utente che aggiorna contemporaneamente le entità nel gruppo di entità. In questo caso, l'API Datastore riprova la transazione per un numero fisso di volte. Se tutte le operazioni non risolvono il problema, db.run_in_transaction() genera un TransactionFailedError. Puoi modificare il numero di tentativi per la transazione utilizzando db.run_in_transaction_custom_retries() anziché db.run_in_transaction().

Allo stesso modo, la funzione Transaction non deve avere effetti collaterali che dipendono dal successo della transazione, a meno che il codice che chiama la funzione Transaction non sappia di dover annullare questi effetti. Ad esempio, se la transazione archivia una nuova entità Datastore, salva l'ID dell'entità creata per un utilizzo successivo, quindi la transazione non va a buon fine e l'ID salvato non fa riferimento all'entità prevista perché è stato eseguito il rollback della creazione dell'entità. In questo caso, il codice di chiamata deve fare attenzione a non utilizzare l'ID salvato.

Isolamento e coerenza

Al di fuori delle transazioni, il livello di isolamento di Datastore è il più vicino al commit di lettura. All'interno delle transazioni viene applicato l'isolamento serializzabile. Ciò significa che un'altra transazione non può modificare contemporaneamente i dati letti o modificati da questa transazione.

In una transazione, tutte le letture riflettono lo stato attuale e coerente di Datastore nel momento in cui è iniziata la transazione. Per le query e l'accesso all'interno di una transazione è garantito un unico snapshot coerente del datastore a partire dall'inizio della transazione. Le entità e le righe dell'indice nel gruppo di entità della transazione vengono completamente aggiornate in modo che le query restituiscano l'insieme completo e corretto di entità di risultato, senza falsi positivi o falsi negativi che possono verificarsi nelle query al di fuori delle transazioni.

Questa visualizzazione coerente degli snapshot si estende anche alle letture dopo le scritture all'interno delle transazioni. A differenza della maggior parte dei database, le query e le interazioni all'interno di una transazione del datastore non mostrano i risultati delle scritture precedenti all'interno della transazione. Nello specifico, se un'entità viene modificata o eliminata all'interno di una transazione, una query o un get restituisce la versione originale dell'entità all'inizio della transazione o nulla se l'entità non esisteva.

Utilizzi per le transazioni

Questo esempio mostra un utilizzo delle transazioni: l'aggiornamento di un'entità con un nuovo valore della proprietà rispetto al suo valore attuale.

def increment_counter(key, amount):
    obj = db.get(key)
    obj.counter += amount
    obj.put()

Avviso: l'esempio precedente illustra l'incremento transazionale di un contatore solo per semplicità. Se la tua app dispone di contatori che vengono aggiornati di frequente, non devi incrementarli a livello transazionale o nemmeno all'interno di una singola entità. Una best practice per lavorare con i contatori è suddividere il contatore in più parti, sceglierne una a caso quando devi incrementare il contatore e sommare le parti per ottenere il conteggio totale.

Ciò richiede una transazione perché il valore potrebbe essere aggiornato da un altro utente dopo che questo codice ha recuperato l'oggetto, ma prima che venga salvato l'oggetto modificato. Senza una transazione, la richiesta dell'utente utilizza il valore di count prima dell'aggiornamento dell'altro utente e il salvataggio sovrascrive il nuovo valore. Con una transazione, all'applicazione viene comunicato l'aggiornamento dell'altro utente. Se l'entità viene aggiornata durante la transazione, la transazione viene ripetuta fino al completamento di tutti i passaggi senza interruzioni.

Un altro utilizzo comune delle transazioni è recuperare un'entità con una chiave denominata o crearla se non esiste ancora:

class SalesAccount(db.Model):
    address = db.PostalAddressProperty()
    phone_number = db.PhoneNumberProperty()

def get_or_create(parent_key, account_id, address, phone_number):
    obj = db.get(db.Key.from_path("SalesAccount", account_id, parent=parent_key))
    if not obj:
        obj = SalesAccount(key_name=account_id,
                           parent=parent_key,
                           address=address,
                           phone_number=phone_number)
        obj.put()
    else:
        obj.address = address
        obj.phone_number = phone_number

Come in precedenza, una transazione è necessaria per gestire il caso in cui un altro utente tenti di creare o aggiornare un'entità con lo stesso ID stringa. Senza una transazione, se l'entità non esiste e due utenti tentano di crearla, il secondo sovrascrive la prima senza sapere che è avvenuta. Con una transazione, il secondo tentativo riprova, nota che l'entità ora esiste e aggiorna invece l'entità.

Quando una transazione non va a buon fine, puoi fare in modo che la tua app riprovi la transazione finché non va a buon fine oppure puoi consentire agli utenti di gestire l'errore propagandolo al livello di interfaccia utente della tua app. Non è necessario creare un ciclo di nuovo tentativo per ogni transazione.

Get-or-create è così utile che esiste un metodo integrato: Model.get_or_insert() prende il nome di una chiave, un elemento padre facoltativo e gli argomenti da passare al costruttore del modello se non esiste un'entità con quel nome e quel percorso. Il tentativo di recupero e la creazione avvengono in una sola transazione. Di conseguenza, se la transazione ha esito positivo, il metodo restituisce sempre un'istanza del modello che rappresenta un'entità effettiva.

Nota: una transazione deve avvenire il più rapidamente possibile per ridurre la probabilità che le entità utilizzate dalla transazione cambino, causando il mancato completamento della transazione. Il più possibile, prepara i dati al di fuori della transazione, quindi esegui la transazione per eseguire operazioni su Datastore che dipendono da uno stato coerente. L'applicazione deve preparare le chiavi per gli oggetti utilizzati al di fuori della transazione e recuperare le entità all'interno della transazione.

Infine, puoi utilizzare una transazione per leggere uno snapshot coerente di Datastore. Questo può essere utile quando sono necessarie più letture per eseguire il rendering di una pagina o esportare dati che devono essere coerenti. Questi tipi di transazioni vengono spesso denominati transazioni di sola lettura, in quanto non eseguono operazioni di scrittura. Le transazioni per gruppo singolo di sola lettura non falliscono mai a causa di modifiche simultanee, quindi non è necessario implementare nuovi tentativi in caso di errore. Tuttavia, le transazioni tra gruppi possono avere esito negativo a causa di modifiche simultanee, pertanto dovrebbero essere effettuati nuovi tentativi. Il commit e il rollback di una transazione di sola lettura sono operazioni autonome.

class Customer(db.Model):
    user = db.StringProperty()

class Account(db.Model):
    """An Account has a Customer as its parent."""
    address = db.PostalAddressProperty()
    balance = db.FloatProperty()

def get_all_accounts():
    """Returns a consistent view of the current user's accounts."""
    accounts = []
    for customer in Customer.all().filter('user =', users.get_current_user().user_id()):
        accounts.extend(Account.all().ancestor(customer))
    return accounts

Attività transazionale in coda

Puoi accodare un'attività come parte di una transazione Datastore, in modo che venga accodata solo se il commit della transazione viene eseguito correttamente. Se non viene eseguito il commit della transazione, l'attività non viene messa in coda. Se viene eseguito il commit della transazione, l'attività viene accodata. Una volta accodato, l'attività non verrà eseguita immediatamente, quindi non è atomica con la transazione. Tuttavia, una volta inserita in coda, l'attività riproverà finché non avrà esito positivo. Questo vale per qualsiasi attività accodata durante una funzione run_in_transaction().

Le attività transazionali sono utili perché consentono di combinare le azioni non relative al datastore in una transazione che dipende dalla riuscita della transazione (ad esempio, l'invio di un'email per la conferma di un acquisto). Puoi anche associare le azioni Datastore alla transazione, ad esempio eseguire il commit delle modifiche ai gruppi di entità al di fuori della transazione se e solo se la transazione ha esito positivo.

Un'applicazione non può inserire più di cinque attività transazionali nelle code di attività durante una singola transazione. Le attività transazionali non devono avere nomi specificati dall'utente.

def do_something_in_transaction(...)
    taskqueue.add(url='/path/to/my/worker', transactional=True)
  ...

db.run_in_transaction(do_something_in_transaction, ....)