/ /

Driver Rust

Operações CRUD

Página inicial do Docs

Bibliotecas do cliente

Rust

Driver Rust

Operações CRUD

Transações

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()`	Inicia uma nova transação nesta sessão. A sessão deve ser passada para cada operação dentro da transação, ou a operação será executada fora da transação. Você pode definir opções de transação encadeando os métodos do construtor de opções `TransactionOptions` para `start_transaction()`. Os erros retornados das operações executadas na transação podem incluir um rótulo `TRANSIENT_TRANSACTION_ERROR`, que indica que toda a transação pode ser encerrada e, em seguida, repetida com a expectativa de que seja bem-sucedida.
`commit_transaction()`	Confirma a transação ativa para esta sessão. Este método retorna um erro se não houver transação ativa para a sessão ou se a transação tiver sido encerrada anteriormente. Este método pode retornar um erro que inclui um rótulo `UNKNOWN_TRANSACTION_COMMIT_RESULT`, o que indica que não se sabe se a transação confirmada satisfaz o write concern definido. Se você encontrar esse erro, é seguro tentar novamente a confirmação até que o write concern seja satisfeito ou o método retorne um erro sem o rótulo.
`abort_transaction()`	Termina a transação ativa para esta sessão. Esse método retorna um erro se não houver uma transação ativa para a sessão ou se a transação tiver sido confirmada ou encerrada.
`and_run()`	Executa a chamada de resposta fornecida e, em seguida, confirma ou encerra a transação. O driver tenta novamente as chamadas de resposta e confirmações que geram um erro com um rótulo `TRANSIENT_TRANSACTION_ERROR`. Se eles gerarem qualquer outro erro, o driver encerra a transação e retorna o erro para o chamador. Ao usar esse método para executar uma transação, o driver lida automaticamente com quaisquer erros, para que você possa optar por omitir o código de tratamento de erros. Como a chamada de resposta retorna um futuro e pode ser executada várias vezes, as regras de empréstimo de fechamento da linguagem Rust para valores capturados podem ser restritivas. Portanto, o método `and_run()` aceita um parâmetro de contexto que é passado para a chamada de resposta. Parâmetros: contexto `C`, chamada de resposta `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 guia de 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

Operações de gravação em massa

Operações compostas