Transazioni

Nota:gli sviluppatori che creano nuove applicazioni sono fortemente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione automatica nella cache delle entità tramite l'API Memcache. Se al momento utilizzi la libreria client DB precedente, leggi la guida alla migrazione da DB a NDB.

Datastore supporta le transazioni. Una transazione è un'operazione o un insieme di operazioni atomiche: tutte le operazioni nella transazione vengono eseguite o nessuna di loro. 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 come atomica, il che significa che le transazioni non vengono mai applicate parzialmente. Vengono applicate tutte le operazioni nella transazione oppure nessuna. Le transazioni hanno una durata massima di 60 secondi con un periodo di scadenza di inattività di 10 secondi dopo 30 secondi.

Un'operazione potrebbe non riuscire quando:

• Sono stati tentati troppi modifiche simultanee allo stesso gruppo di entità.
• La transazione supera un limite di risorse.
• Datastore rileva un errore interno.

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

Nota :se la tua applicazione riceve un'eccezione durante il commit di una transazione, non significa sempre che la transazione non è andata a buon fine. Puoi ricevere Timeout, TransactionFailedError o InternalError eccezioni nei casi in cui le transazioni sono state eseguite e alla fine verranno applicate correttamente. Se possibile, rendi idempotenti le transazioni Datastore in modo che se ripeti una transazione, il risultato finale sia lo stesso.

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

Un'applicazione può eseguire un insieme di istruzioni e operazioni di datastore in una singola transazione, in modo che se un'istruzione o un'operazione genera un'eccezione, nessuna delle operazioni di Datastore nel set venga applicata. 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 a entità all'interno di un singolo gruppo di entità o che sia una transazione tra gruppi.

Per il caso d'uso comune di una funzione utilizzata solo all'interno delle transazioni, utilizza il decoratore @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, anziché 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() accetta l'oggetto funzione e gli argomenti posizionali e di parole chiave da passare alla funzione. Se la funzione restituisce un valore, db.run_in_transaction() restituisce quel valore.

Se la funzione restituisce un valore, la transazione viene eseguita e tutti gli effetti delle operazioni Datastore vengono applicati. Se la funzione genera un'eccezione, la transazione viene "annullata" e gli effetti non vengono applicati. Consulta 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 di quella esistente, ma questo comportamento non è ancora supportato e genera db.BadRequestError. Puoi specificare altri comportamenti. Per maggiori dettagli, consulta la documentazione di riferimento della funzione sulle opzioni di transazione.

Utilizzo delle transazioni cross-group (XG)

Le transazioni tra gruppi, che operano su più gruppi di entità, si comportano come le transazioni di un singolo gruppo, ma non hanno esito negativo se il codice tenta di aggiornare le entità di più di un gruppo di entità. Per richiamare una transazione tra gruppi, utilizza le opzioni di transazione.

Utilizzo di @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()

Utilizzo di 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)

Cosa si può fare in una transazione

Datastore impone limitazioni a ciò che può essere fatto all'interno di una singola transazione.

Tutte le operazioni Datastore in una transazione devono operare su entità nello stesso gruppo di entità se la transazione è una transazione a gruppo singolo oppure su entità in un massimo di 25 gruppi di entità se la transazione è una transazione tra gruppi. Ciò include l'interrogazione delle entità per predecessore, il recupero delle entità per chiave, l'aggiornamento delle entità e l'eliminazione delle 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&#3entità baseà principale, a meno che non si tratti di una transazione tra gruppi.

Quando due o più transazioni tentano contemporaneamente di modificare entità in uno o più gruppi di entità comuni, solo la prima transazione che esegue il commit delle modifiche può riuscire; tutte le altre non riusciranno a eseguire il commit. A causa di questa progettazione, l'utilizzo di gruppi di entità limita il numero di scritture simultanee che puoi eseguire su qualsiasi entità nei gruppi. Quando inizia una transazione, Datastore utilizza il controllo della concorrenza ottimistico controllando l'ora dell'ultimo aggiornamento dei gruppi di entità utilizzati nella transazione. Quando esegui 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 è cambiato rispetto al controllo iniziale, viene generata un'eccezione.

Un'app può eseguire una query durante una transazione, ma solo se include un filtro di antenati. Un'app può anche ottenere entità Datastore per chiave durante una transazione. Puoi preparare le chiavi prima della transazione oppure puoi crearle all'interno della transazione con nomi o ID chiave.

Tutto il resto del codice Python è consentito all'interno di una funzione di transazione. Puoi determinare se l'ambito corrente è nidificato in una funzione di transazione utilizzando db.is_in_transaction(). La funzione di transazione non deve avere effetti collaterali diversi dalle operazioni Datastore. La funzione di transazione può essere chiamata più volte se un'operazione Datastore non riesce perché un altro utente aggiorna le entità nel gruppo di entità contemporaneamente. In questo caso, l'API Datastore riprova la transazione un numero fisso di volte. Se tutti i controlli non vanno a buon fine, db.run_in_transaction() genera un TransactionFailedError. Puoi modificare il numero di tentativi di ripetizione della transazione utilizzando db.run_in_transaction_custom_retries() anziché db.run_in_transaction().

Allo stesso modo, la funzione di transazione non deve avere effetti collaterali che dipendono dall'esito positivo della transazione, a meno che il codice che chiama la funzione di transazione non sappia come annullare questi effetti. Ad esempio, se la transazione archivia una nuova entità Datastore, salva l'ID dell'entità creata per un utilizzo successivo e la transazione non va a buon fine, l'ID salvato non fa riferimento all'entità prevista perché la creazione dell'entità è stata eseguita il rollback. Il codice chiamante deve fare attenzione a non utilizzare l'ID salvato in questo caso.

Isolamento e coerenza

Al di fuori delle transazioni, il livello di isolamento di Datastore è più vicino a Read Committed. 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 al momento dell'inizio della transazione. Le query e le operazioni di recupero all'interno di una transazione garantiscono la visualizzazione di un singolo snapshot coerente di Datastore all'inizio della transazione. Le entità e le righe dell'indice nel gruppo di entità della transazione vengono aggiornate completamente in modo che le query restituiscano l'insieme completo e corretto di entità dei risultati, senza i falsi positivi o i falsi negativi che possono verificarsi nelle query al di fuori delle transazioni.

Questa visualizzazione coerente dello snapshot si estende anche alle letture dopo le scritture all'interno delle transazioni. A differenza della maggior parte dei database, le query e i recuperi all'interno di una transazione Datastore non vedono i risultati delle scritture precedenti all'interno di quella transazione. Nello specifico, se un'entità viene modificata o eliminata all'interno di una transazione, una query o un'operazione get restituisce la versione originale dell'entità all'inizio della transazione o nulla se l'entità non esisteva in quel momento.

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 riportato sopra mostra l'incremento transazionale di un contatore solo per semplicità. Se la tua app ha contatori che vengono aggiornati di frequente, non devi incrementarli in modo transazionale o anche 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 recupera l'oggetto, ma prima che lo salvi. 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, l'applicazione viene informata dell'aggiornamento dell'altro utente. Se l'entità viene aggiornata durante la transazione, quest'ultima viene ritentata finché tutti i passaggi non vengono completati 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, è necessaria una transazione per gestire il caso in cui un altro utente tenta 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 il primo senza sapere che è successo. Con una transazione, il secondo tentativo riprova, nota che l'entità ora esiste e la aggiorna.

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 lasciare che gli utenti gestiscano l'errore propagandolo al livello dell'interfaccia utente della tua app. Non è necessario creare un ciclo di nuovi tentativi per ogni transazione.

Get-or-create è così utile che esiste un metodo integrato per farlo: Model.get_or_insert() accetta un nome chiave, un elemento padre facoltativo e argomenti da passare al costruttore del modello se non esiste un'entità con quel nome e percorso. Il tentativo di recupero e la creazione avvengono in un'unica transazione, quindi (se la transazione va a buon fine) 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 l'esito negativo della transazione. Per quanto possibile, prepara i dati al di fuori della transazione, quindi esegui la transazione per eseguire le operazioni Datastore che dipendono da uno stato coerente. L'applicazione deve preparare le chiavi per gli oggetti utilizzati al di fuori della transazione, quindi recuperare le entità all'interno della transazione.

Infine, puoi utilizzare una transazione per leggere uno snapshot coerente di Datastore. Questa opzione può essere utile quando sono necessarie più letture per visualizzare una pagina o esportare dati che devono essere coerenti. Questi tipi di transazioni sono spesso chiamati transazioni di sola lettura, poiché non eseguono scritture. Le transazioni di sola lettura con un solo gruppo non hanno mai esito negativo a causa di modifiche simultanee, quindi non devi implementare i tentativi in caso di errore. Tuttavia, le transazioni tra gruppi possono non riuscire a causa di modifiche simultanee, pertanto devono essere riprovate. Il commit e il rollback di una transazione di sola lettura sono entrambi no-op.

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

Accodamento delle attività transazionali

Puoi mettere in coda un'attività nell'ambito di una transazione Datastore, in modo che l'attività venga messa in coda solo se la transazione viene eseguita correttamente. Se il commit della transazione non viene eseguito, l'attività non viene inserita nella coda. Se viene eseguito il commit della transazione, l'attività viene inserita nella coda. Una volta accodata, l'attività non verrà eseguita immediatamente, pertanto non è atomica con la transazione. Tuttavia, una volta accodata, l'attività verrà ritentata finché non andrà a buon fine. Ciò vale per qualsiasi attività accodata durante una funzione run_in_transaction().

Le attività transazionali sono utili perché ti consentono di combinare azioni non Datastore a una transazione che dipende dalla riuscita della transazione (ad esempio l'invio di un'email per confermare un acquisto). Puoi anche collegare le azioni Datastore alla transazione, ad esempio per 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 in 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, ....)