Transações

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 usar o PyMongo, você pode criar uma nova sessão a partir de uma instância MongoClient como tipo 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.

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 :

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.

# Incorrect: leaks the session because no reference exists to call
# end_session() on once finished with it
with client.start_session().bind(end_session=False):
    ...
# Correct: end_session=True by default, so session ends automatically
with client.start_session().bind():
    ...
# Correct: session variable allows explicit cleanup
with client.start_session() as s, s.bind(end_session=False):
    ...
s.end_session()
# Correct: nested context managers
with client.start_session() as s:
    with s.bind():
        ...

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:

1. Crie uma sessão a partir do cliente usando o método start_session(). Vincule-o a todas as operações no bloco chamando o método bind().

2. Use o método with_transaction() para iniciar uma transação.

3. Insere vários documentos. Como a sessão está vinculada, você pode omitir o argumento session de cada operação. O método with_transaction() executa a operação de inserção e confirma a transação. Se qualquer operação resultar em erros, o with_transaction() cancelará a transação. Este método garante que a sessão feche corretamente quando o bloco sair.

4. Feche a conexão com o servidor usando o método client.close() .

Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

# 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
async 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()

# Establishes a connection to the MongoDB server
client = AsyncMongoClient("<connection string>")
# Defines the database and collection
restaurants_db = client["sample_restaurants"]
restaurants_collection = restaurants_db["restaurants"]
# Function performs the transaction
async 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
    await restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Pizza", "cuisine": "Pizza"}, session=session
    )
    await 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).
        await session.with_transaction(insert_documents)
        print("Transaction succeeded")
    except (ConnectionFailure, OperationFailure) as e:
        print(f"Transaction failed: {e}")
# Closes the client connection
await 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.

Informações adicionais

Para saber mais sobre os conceitos mencionados neste guia, consulte as seguintes páginas no manual do MongoDB Server :

• Transações

• Sessões do servidor

• Isolamento de leitura, consistência e atualidade

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 .