Uma transação é um conjunto de operações em uma ou mais entidades. Todas as transações são atômicas, o que significa que elas nunca são aplicadas parcialmente. Ou todas as operações na transação são aplicadas ou nenhuma delas é aplicada.
Como usar transações
As transações expiram após 270 segundos ou se ficam inativas por 60 segundos.
Uma operação poderá falhar quando:
- muitas modificações simultâneas forem tentadas na mesma entidade;
- a transação exceder um limite de recursos;
- o banco de dados do modo Datastore encontrar um erro interno.
Em todos esses casos, a API Datastore retorna um erro.
As transações são um recurso opcional. Usar transações para executar operações do banco de dados não é obrigatório.
Um aplicativo executa um conjunto de instruções e operações em uma única transação. Assim, caso alguma instrução ou operação gere uma exceção, não será aplicada nenhuma operação do banco de dados no conjunto. O aplicativo define as ações a serem executadas na transação.
Veja o snippet a seguir como realizar uma transação. A transação é uma transferência monetária de uma conta para outra.
C#
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Para manter nossos exemplos mais sucintos, às vezes omitimos rollback
se a transação falha. Em código de produção, é importante garantir que cada transação seja executada explicitamente ou revertida.
O que pode ser feito em uma transação
As transações podem consultar ou procurar qualquer número de entidades. O tamanho máximo de uma transação é de 10 MiB. É possível usar uma transação de leitura/gravação ou uma transação somente leitura.
Isolamento e consistência
Bancos de dados do modo Datastore implementam o isolamento serializável. Os dados lidos ou modificados por uma transação não podem ser modificados simultaneamente.
As consultas e pesquisas de uma transação analisam um instantâneo consistente do estado do banco de dados. Esse instantâneo contém o efeito de todas as transações e grava o que foi concluído antes do início da transação.
A visualização desse instantâneo consistente também se estende a leituras após gravações dentro de transações. Diferentemente da maioria dos bancos de dados, as consultas e pesquisas dentro de uma transação do Cloud Datastore não exibem os resultados de gravações anteriores dentro dessa transação. Especificamente, se uma entidade é modificada ou excluída em uma transação, uma consulta ou pesquisa retorna a versão original da entidade no início da transação ou nada, se a entidade não existia.
Fora das transações, as consultas e pesquisas também têm isolamento serializável.
Modos de simultaneidade
O Firestore no modo Datastore oferece suporte a três modos de simultaneidade. O modo de simultaneidade é uma configuração de banco de dados que determina como as transações simultâneas interagem. Você pode selecionar um dos seguintes modos de simultaneidade:
Pessimista
Transações de leitura/gravação usam bloqueios de leitor/gravador para implementar o isolamento e a serialização. Quando duas ou mais transações de leitura/gravação simultâneas leem ou gravam os mesmos dados, o bloqueio retido por uma transação pode atrasar as outras transações. Se sua transação não exigir gravações, será possível melhorar o desempenho e evitar a contenção com outras transações usando uma transação somente leitura. As transações somente leitura não exigem bloqueios.
Os bancos de dados do Firestore no modo Datastore usam o modo de simultaneidade pessimista por padrão.
Otimista
Quando duas ou mais transações de leitura/gravação simultâneas leem ou gravam os mesmos dados, somente a primeira transação que faz o commit das mudanças é bem-sucedida. Outras transações que executam gravações falham na confirmação.
Otimismo com grupos de entidades
Use esse modo de simultaneidade somente se o app depender da semântica transacional do grupo de entidades do Cloud Datastore legados. Esse modo de simultaneidade impõe limites adicionais às transações:
- As transações são limitadas a 25 grupos de entidades.
- As gravações em um grupo de entidades são limitadas a uma por segundo.
- As consultas em transações precisam ser consultas de ancestral.
Conferir o modo de simultaneidade
Use o recurso REST projects.databases do Firestore para conferir o modo de simultaneidade do seu banco de dados:
curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases"
Mudar o modo de simultaneidade
Para mudar o modo de simultaneidade do banco de dados, envie uma solicitação PATCH
para o recurso REST
projects.databases
do Firestore:
curl --request PATCH \
--header "Authorization: Bearer "$(gcloud auth print-access-token) \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"concurrencyMode":"CONCURRENCY_MODE"}' \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases/(default)?updateMask=concurrencyMode"
em que:
- CONCURRENCY_MODE é
PESSIMISTIC
,OPTIMISTIC
ouOPTIMISTIC_WITH_ENTITY_GROUPS
; - PROJECT_ID é o ID do seu projeto do Google Cloud.
Usos das transações
Um dos usos das transações é a atualização de uma entidade com um novo valor de propriedade relativo
ao seu valor atual. O exemplo transferFunds
acima faz isso para duas
entidades, retirando dinheiro de uma conta e transferindo-o para outra.
A API Datastore não tenta repetir transações automaticamente, mas é possível
adicionar sua própria lógica para repeti-las, por exemplo, para lidar com conflitos quando
outra solicitação atualiza a mesma entidade ao mesmo tempo.
C#
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Isso requer uma transação porque o valor de balance
em uma entidade pode ser atualizado por outro usuário após esse código buscar o objeto, mas antes de salvar o objeto modificado. Sem uma transação, a solicitação do usuário usa o valor de balance
antes da atualização do outro usuário, e a gravação substitui o novo valor. Com uma
transação, o aplicativo é informado sobre a atualização.
Outro uso comum das transações é buscar uma entidade com uma chave nomeada, ou criá-la, caso ela ainda não exista (este exemplo é baseado no exemplo da TaskList de como criar uma entidade):
C#
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Como antes, uma transação é necessária para manipular o caso quando outro usuário estiver tentando criar ou atualizar uma entidade com o mesmo ID de string. Sem uma transação, se a entidade não existir e dois usuários tentarem criá-la, o segundo substituirá o primeiro sem saber o que aconteceu.
Quando uma transação falha, é possível fazer com que o app repita a transação até ter êxito, ou é possível deixar que os usuários lidem com o erro propagando-o até o nível de interface do usuário do app. Não é necessário criar um ciclo de repetições em torno de cada transação.
Transações somente leitura
Por fim, é possível usar uma transação para ler um instantâneo consistente do banco de dados. Isso pode ser útil quando forem necessárias várias leituras para renderizar uma página ou para exportar dados que precisam ser consistentes. É possível criar uma transação somente leitura para esses casos.
As transações somente leitura não podem modificar entidades, mas, em contrapartida, não entram em conflito com outras transações e não precisam ser repetidas. Se alguma transação regular de leitura/gravação executar apenas leituras, essa transação pode entrar em conflito com transações que modificam os mesmos dados.
C#
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Cloud Datastore, consulte as Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.
Para autenticar no Cloud Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.