Transações
Nesta página
Visão geral
Neste guia, você pode aprender como usar o driver PyMongo para executar transações. As transações permitem que você execute uma série de operações que não alteram nenhum dado até que a transação seja confirmada. Se qualquer operação na transação retornar um erro, o driver cancelará a transação e descartará todas as alterações de dados antes que elas se tornem visíveis.
No MongoDB, as transações são executadas dentro de sessões lógicas . Uma sessão é um agrupamento de operações de leitura ou escrita relacionadas que você pretende executar sequencialmente. As sessões permitem que você execute operações em uma transação compatível com ACID, que é uma transação que atende a uma expectativa de atomicidade, consistência, isolamento e durabilidade. O MongoDB garante que os dados envolvidos em suas operações de transação permaneçam consistentes, mesmo que as operações encontrem erros inesperados.
Ao utilizar o PyMongo, você pode criar uma nova sessão a partir de uma instância do MongoClient
como um tipo do ClientSession
. Recomendamos que você reutilize seu MongoClient
para várias sessões e transações, em vez de criar um novo cliente a cada vez.
Aviso
Utilize uma ClientSession
apenas com o MongoClient
(ou MongoDatabase
ou MongoCollection
associada) que a criou. Utilizar uma ClientSession
com um MongoClient
diferente resulta em erros de operação.
Consistência causal
O MongoDB permite consistência causal nas sessões do cliente . O modelo de consistência causal garante que as operações dentro de uma sessão sejam executadas em uma ordem causal. Os clientes observam resultados consistentes com as relações causais ou as dependências entre as operações. Por exemplo, se você executar uma série de operações em que uma operação depende logicamente do resultado de outra, todas as leituras subsequentes refletirão o relacionamento de dependência .
A tabela a seguir descreve as garantias que as sessões causalmente consistentes oferecem:
Garantia | Descrição |
---|---|
Ler suas gravações | As operações de leitura refletem os resultados das operações de gravação anteriores. |
Leituras monotônicas | As operações de leitura não retornam resultados que reflitam um estado de dados anterior a uma operação de leitura anterior. |
Escritas monotônicas | Se uma operação de gravação precisar preceder outras operações de gravação, o driver executará essa operação de gravação primeiro. Por exemplo, se você chamar |
Escritas que seguem as leituras | Se uma operação de gravação precisar seguir outras operações de leitura, o driver executará primeiro as operações de leitura. Por exemplo, se você chamar |
Em uma sessão causalmente consistente, o MongoDB garante uma relacionamento causal entre as seguintes operações:
Operações de leitura que têm uma preocupação de leitura
majority
Operações de escrita que têm preocupação de gravação
majority
Dica
Para saber mais sobre os conceitos mencionados nesta seção, consulte as seguintes entradas de manual do MongoDB Server :
Dados de amostra
Os exemplos neste guia usam a sample_restaurants.restaurants
collection dos conjuntos de dados de amostra do Atlas . Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte o tutorialIntrodução ao PyMongo.
Métodos
Após iniciar uma sessão usando o método start_session()
, você pode gerenciar o estado da sessão usando os seguintes métodos fornecidos pelo ClientSession
retornado :
Método | Descrição |
---|---|
| Starts a new transaction, configured with the given options, on
this session. Returns an error if there is already
a transaction in progress for the session. To learn more about
this method, see the startTransaction() page in the Server manual. Parameters: read_concern , write_concern , read_preference , max_commit_time_ms Return Type: ContextManager |
| Ends the active transaction for this session. Returns an
error if there is no active transaction for the session or the
transaction has been committed or ended. To learn more about
this method, see the abortTransaction() page in the Server manual. |
| Commits the active transaction for this session. Returns an
error if there is no active transaction for the session or if the
transaction was ended. To learn more about
this method, see the commitTransaction() page in the Server manual. |
| Starts a transaction on this session and runs callback once, then
commits the transaction. In the event of an exception, this method may retry
the commit or the entire transaction, which may invoke the callback multiple
times by a single call to with_transaction() .Parameters: callback , read_concern , write_concern , read_preference , max_commit_time_ms Return Value: The result of the callback function |
| Finishes this session. If a transaction has started, this method aborts it.
Returns an error if there is no active session to end. |
Um ClientSession
também tem métodos para recuperar propriedades da sessão e modificar propriedades da sessão mutáveis. Para saber mais sobre esses métodos, consulte a documentação da API.
Exemplo
O exemplo a seguir mostra como você pode criar uma sessão, criar uma transação e confirmar uma operação de inserção de vários documentos por meio das seguintes etapas:
Crie uma sessão a partir do cliente usando o método
start_session()
.Use o método
with_transaction()
para iniciar uma transação.Insere vários documentos. O método
with_transaction()
executa a operação de inserção e confirma a transação. Se qualquer operação resultar em erros, owith_transaction()
cancelará a transação. Este método garante que a sessão feche corretamente quando o bloco sair.Feche a conexão com o servidor usando o método
client.close()
.
# Establishes a connection to the MongoDB server client = MongoClient("<connection string>") # Defines the database and collection restaurants_db = client["sample_restaurants"] restaurants_collection = restaurants_db["restaurants"] # Function performs the transaction def insert_documents(session): restaurants_collection_with_session = restaurants_collection.with_options( write_concern=WriteConcern("majority"), read_concern=ReadConcern("local") ) # Inserts documents within the transaction restaurants_collection_with_session.insert_one( {"name": "PyMongo Pizza", "cuisine": "Pizza"}, session=session ) restaurants_collection_with_session.insert_one( {"name": "PyMongo Burger", "cuisine": "Burger"}, session=session ) # Starts a client session with client.start_session() as session: try: # Uses the with_transaction method to start a transaction, execute the callback, and commit (or abort on error). session.with_transaction(insert_documents) print("Transaction succeeded") except (ConnectionFailure, OperationFailure) as e: print(f"Transaction failed: {e}") # Closes the client connection client.close()
Se você precisar de mais controle sobre suas transações, poderá usar o método start_transaction()
. Você pode usar esse método com os métodos commit_transaction()
e abort_transaction()
descritos na seção anterior para gerenciar manualmente o ciclo de vida da transação.
Observação
Operações paralelas não suportadas
O PyMongo não suporta a execução de operações paralelas em uma única transação.
Se você estiver usando o MongoDB Server v8.0 ou posterior, poderá executar operações de gravação em vários namespaces em uma única transação, chamando o bulk_write()
método em uma MongoClient
instância do. Para obter mais informações, consulte o guia de Operações de Gravação em Massa.
Informações adicionais
Para saber mais sobre os conceitos mencionados neste guia, consulte as seguintes páginas no manual do servidor:
Para saber mais sobre a ACID compliance, consulte Quais são as propriedades ACID nos sistemas de gerenciamento de banco de dados? artigo no site do MongoDB .
Documentação da API
Para saber mais sobre qualquer um dos tipos ou métodos discutidos neste guia, consulte a seguinte documentação da API: