/ /

Driver Kotlin Coroutine

Página inicial do Docs

Bibliotecas do cliente

Kotlin

Driver Kotlin Coroutine

Página inicial do Docs

Bibliotecas do cliente

Kotlin

Driver Kotlin Coroutine

Transações

Visão geral

Neste guia, você pode aprender como usar o driver Kotlin para executar transações. Astransaçõ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 gravação relacionadas que você pretende executar sequencialmente. As sessões permitem consistência causal para um grupo de operações ou permitem que você execute operações em uma transação ACID. 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 Kotlin , você pode criar uma nova sessão a partir de uma instância MongoClient como ClientSession. Recomendamos que você reutilize seu cliente para várias sessões e transações, em vez de fazer a instância de 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 em determinadas sessões de cliente. O modelo de consistência causal garante que, em um sistema distribuído, 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 .

Para garantir a consistência causal, as sessões de cliente devem atender aos seguintes requisitos:

Ao iniciar uma sessão, o driver deve habilitar a opção de consistência causal. Esta opção está habilitada por padrão.
As operações devem ser executadas em uma única sessão em um único thread. Caso contrário, as sessões ou threads devem comunicar os valores de tempo de operation time e de tempo de cluster entre si. Para visualizar um exemplo de duas sessões que comunicam esses valores, consulte os exemplos de Consistência causal no manual do servidor MongoDB.
Você deve usar uma preocupação de leitura ReadConcern.MAJORITY .
Você deve usar uma preocupação de gravação WriteConcern.MAJORITY . Este é o valor padrão de preocupação de gravação .

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 servidor executará essa operação de gravação primeiro. Por exemplo, se você chamar `insertOne()` para inserir um documento e, em seguida, chamar `updateOne()` para modificar o documento inserido, o servidor executará a operação de inserção primeiro.
Escritas que seguem as leituras	Se uma operação de gravação precisar seguir outras operações de leitura, o servidor executará primeiro as operações de leitura. Por exemplo, se você chamar `find()` para recuperar um documento e, em seguida, chamar `deleteOne()` para excluir o documento recuperado, o servidor executará primeiro a operação de localização.

Dica

Para aprender mais sobre os conceitos mencionados nesta seção, consulte as seguintes entradas manuais do servidor MongoDB :

Métodos

Crie um ClientSession utilizando o método startSession() na sua instância do Client . Você pode então modificar o estado da sessão usando os seguintes métodos:

Método	Descrição
`startTransaction()`	Starts a new transaction for this session with the default transaction options. You cannot start a transaction if there's already an active transaction on the session. To set transaction options, use `startTransaction(transactionOptions: TransactionOptions)`.
`abortTransaction()`	Ends the active transaction for this session. Returns an error if there is no active transaction for the session or the transaction was previously ended.
`commitTransaction()`	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.

Dica

Tempo limite da transação

Você pode definir um limite de tempo para que as operações sejam concluídas em suas transações. Para saber mais, consulte a seção Transações do guia Limitar o tempo de execução do servidor.

Um ClientSession também tem métodos para recuperar propriedades da sessão e modificar propriedades da sessão mutáveis. Consulte a documentação da API para saber mais sobre esses métodos.

Exemplo

Este exemplo utiliza a seguinte classe de dados Kotlin para modelar seus documentos:

data class Account(
    val accountId: String,
    val amount: Int
)

O exemplo a seguir demonstra como criar uma sessão, criar uma transação e confirmar alterações em documentos existentes:

Crie uma sessão a partir do cliente utilizando o método startSession().
Use o método startTransaction() para iniciar uma transação.
Atualize os documentos especificados e, em seguida, use o método commitTransaction() se todas as operações forem bem-sucedidas ou abortTransaction() se alguma operação falhar.

// Set up the session
val session = client.startSession()
try {
    session.startTransaction()
    val savingsColl = database
        .getCollection<Account>("savings_accounts")
    val checkingColl = database
        .getCollection<Account>("checking_accounts")
    savingsColl.findOneAndUpdate(
        session,
        eq(Account::accountId.name, "9876"),
        inc(Account::amount.name, -100),
    )
    checkingColl.findOneAndUpdate(
        session,
        eq(Account::accountId.name, "9876"),
        inc(Account::amount.name, 100)
    )
    // Commit the transaction
    val result = session.commitTransaction()
    println("Transaction committed.")
} catch (error: Exception) {
    println("An error occurred during the transaction: ${error.message}")
    // Abort the transaction
    session.abortTransaction()
}

Observação

Operações paralelas não suportadas

O driver Kotlin não suporta a execução de operações paralelas em uma única transação.

Se você estiver usando o servidor MongoDB 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 saber mais, 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 .

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:

Voltar

Operações compostas

Configurar operações CRUD