Transações

Nesta página

Visão geral

Métodos
Exemplo
Informações adicionais
Documentação da API

Visão geral

Neste guia, você pode aprender a usar o driver Rust para executar transações. As transações permitem que você execute uma série de operações que alteram os dados somente se toda a transação for confirmada. Se qualquer operação na transação não for bem-sucedida, o driver interrompe a transação e descarta todas as alterações de dados antes que elas se tornem visíveis. Esse recurso é chamado de atomicidade.

No MongoDB, a transação é executada dentro de sessões lógicas. Uma sessão é um agrupamento de operações de leitura ou escrita relacionadas que você deseja executar sequencialmente. As sessões habilitam a consistência causal para um grupo de operações e 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 driver Rust, você pode criar uma nova sessão a partir de uma instância Client como tipo ClientSession . Você pode melhorar o desempenho do seu aplicativo reutilizando seu cliente para várias sessões e transação, em vez de fazer a instância de um novo cliente a cada vez.

Aviso

Use um ClientSession somente em operações executadas no Client que o criou. Utilizar uma ClientSession com um Client diferente resulta em erros de operação.

Métodos

Crie um ClientSession usando o método start_session() na sua instância Client . Você pode então modificar o estado da sessão utilizando os métodos fornecidos pelo tipo ClientSession . A tabela a seguir descreve esses métodos:

Método	Descrição
`start_transaction()`	Starts a new transaction on this session. The session must be passed into each operation within the transaction, or the operation will run outside of the transaction. You can set transaction options by chaining `TransactionOptions` option builder methods to `start_transaction()`. Errors returned from operations run within the transaction might include a `TRANSIENT_TRANSACTION_ERROR` label, which indicates that the entire transaction can be ended, then retried with the expectation that it will succeed.
`commit_transaction()`	Commits the active transaction for this session. This method returns an error if there is no active transaction for the session or the transaction was previously ended. This method might return an error that includes an `UNKNOWN_TRANSACTION_COMMIT_RESULT` label, which indicates that it is unknown if the committed transaction satisfies the set write concern. If you encounter this error, it is safe to retry the commit until the write concern is satisfied or the method returns an error without the label.
`abort_transaction()`	Ends the active transaction for this session. This method returns an error if there is no active transaction for the session or if the transaction was committed or ended.
`and_run()`	Runs the given callback, then commits or ends the transaction. The driver retries callbacks and commits that raise an error with a `TRANSIENT_TRANSACTION_ERROR` label. If they raise any other error, the driver ends the transaction and returns the error to the caller. When you use this method to perform a transaction, the driver automatically handles any errors, so you can choose to omit error handling code. Because the callback returns a future and can be run multiple times, the Rust language closure borrowing rules for captured values can be restrictive. So, the `and_run()` method accepts a context parameter that is passed to the callback. Parameters: context `C`, callback `FnMut(&'a mut ClientSession, &'a mut C)`

Importante

Métodos que podem ser executados em transação

Para executar operações MongoDB dentro de transações, você deve encadear o método session() à operação. Este método aceita uma instância ClientSession como parâmetro.

Por exemplo, para excluir um documento, geralmente você pode usar o método delete_one() . No entanto, para excluir um documento dentro de uma transação, você deve encadear o método session() a delete_one() e passar a sessão como um parâmetro.

Exemplo

O seguinte código define a chamada de resposta insert_media() que insere dados na collection books e na collection films :

async fn insert_media(session: &mut ClientSession) -> Result<(), Error> {
    let books_coll = session
        .client()
        .database("db")
        .collection::<Document>("books");
    let films_coll = session
        .client()
        .database("db")
        .collection::<Document>("films");
    books_coll
        .insert_one(doc! {
            "name": "Sula",
            "author": "Toni Morrison"
        })
        .session(&mut *session)
        .await?;
    films_coll
        .insert_one(doc! {
            "name": "Nostalgia",
            "year": 1983
        })
        .session(&mut *session)
        .await?;
    Ok(())
}

O código a seguir conclui as seguintes ações para executar a transação:

Cria uma sessão a partir do cliente utilizando o método start_session() .
Chama o método start_transaction() para iniciar uma transação.
Chama o método and_run() para executar a função de chamada de resposta de resposta insert_media() dentro da transação.

let mut session = client.start_session().await?;
session
    .start_transaction()
    .and_run((), |session, _| insert_media(session).boxed())
    .await?;
println!("Successfully committed transaction!");

Successfully committed transaction!

Se você precisar de mais controle sobre suas transações, consulte a documentação da API ClientSession para encontrar um exemplo que mostra como criar e confirmar manualmente uma transação.

Observação

Operações paralelas não suportadas

O driver Rust 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 usando operações de gravação em massa. Para obter mais informações, consulte o guiade operações 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 .

Para saber mais sobre operações de inserção, consulte o guia Inserir documento .

Documentação da API

Para saber mais sobre os métodos e tipos mencionados neste guia, consulte a documentação da API abaixo:

Voltar

Índices de pesquisa do Atlas

Coleções de Time Series