0Pricing
MongoDB Academy · Lekcja

Uruchamianie sesji i transakcji obejmującej wiele dokumentów

Nauczą się Państwo otwierać ClientSession, wykonywać wiele operacji w ramach startTransaction() oraz zatwierdzać lub wycofywać transakcję.

Uruchamianie sesji i transakcji obejmującej wiele dokumentów to bezpłatna lekcja MongoDB Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej MongoDB Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs MongoDB Academy zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Sessions Are the Foundation

MongoDB multi-document transactions require a session. A session is a server-side context that tracks your causally consistent reads and transaction state. You create a session from the MongoClient, pass it to every operation inside the transaction, and then end the session when you are done. Forgetting to pass the session object means operations run outside the transaction and are not rolled back on abort.

Creating a Session With startSession()

Call client.startSession() to obtain a ClientSession object. This does not start a transaction yet—it only establishes the server-side context. Sessions can optionally be configured for causal consistency so that reads within the session always reflect all prior writes in the same session, even on secondaries. Always end the session in a finally block to release server resources.

const { MongoClient } = require('mongodb');
const client = new MongoClient(process.env.MONGODB_URI);

async function run() {
  const session = client.startSession();
  try {
    // ... use session here
  } finally {
    await session.endSession();
    await client.close();
  }
}

Starting a Transaction

Call session.startTransaction() with optional transaction options to begin a multi-document transaction. Common options include readConcern (typically 'snapshot' for full isolation) and writeConcern (typically { w: 'majority' } for durable commits). Once started, all operations that pass this session are part of the transaction and will be rolled back if the transaction aborts.

session.startTransaction({
  readConcern: { level: 'snapshot' },
  writeConcern: { w: 'majority' }
});

Passing the Session to Operations

Every operation you want to include in the transaction must receive the session object as an option. If you forget to pass the session to an operation, it runs outside the transaction with its own independent write that will not be rolled back on abort. This is a common source of bugs in transaction code—always double-check that every insert, update, and delete inside the try block receives the session.

const db = client.db('bank');
const accounts = db.collection('accounts');

// Both operations must receive { session } to be part of the transaction
await accounts.updateOne(
  { _id: fromAccountId },
  { $inc: { balance: -transferAmount } },
  { session }  // <-- REQUIRED
);

await accounts.updateOne(
  { _id: toAccountId },
  { $inc: { balance: transferAmount } },
  { session }  // <-- REQUIRED
);

Committing With commitTransaction()

After all operations complete successfully, call session.commitTransaction() to atomically apply all changes to the database. Until commit is called, none of the transaction's writes are visible to other operations. On commit, MongoDB applies all writes and acknowledges according to the write concern. A successful commit means all operations in the transaction are durably saved.

session.startTransaction();
try {
  await accounts.updateOne({ _id: fromId }, { $inc: { balance: -100 } }, { session });
  await accounts.updateOne({ _id: toId }, { $inc: { balance: 100 } }, { session });
  await session.commitTransaction();
  console.log('Transfer committed successfully');
} catch (error) {
  await session.abortTransaction();
  throw error;
}

Aborting With abortTransaction()

If any operation in the transaction fails or if your application logic determines the transaction should not proceed, call session.abortTransaction(). This rolls back all writes made in the transaction as if none of them happened. MongoDB guarantees that no partial state will be left—other readers will never see any of the aborted transaction's writes.

session.startTransaction();
try {
  const inventory = await db.collection('inventory').findOne({ _id: itemId }, { session });
  
  if (inventory.stock < requestedQty) {
    // Business logic: not enough stock — abort
    await session.abortTransaction();
    return { success: false, reason: 'Insufficient stock' };
  }
  
  await db.collection('inventory').updateOne(
    { _id: itemId }, { $inc: { stock: -requestedQty } }, { session }
  );
  await db.collection('orders').insertOne({ itemId, qty: requestedQty, status: 'confirmed' }, { session });
  await session.commitTransaction();
  return { success: true };
} catch (error) {
  await session.abortTransaction();
  throw error;
}

The withTransaction() Helper

The Node.js driver provides a convenient session.withTransaction(fn) helper that automatically handles starting, committing, and aborting the transaction, including automatic retries for transient errors. The callback function receives the session and should contain all your transaction operations. Using withTransaction is recommended over manual start/commit/abort because it correctly handles the retry logic MongoDB requires.

const session = client.startSession();
try {
  await session.withTransaction(async () => {
    await accounts.updateOne({ _id: fromId }, { $inc: { balance: -100 } }, { session });
    await accounts.updateOne({ _id: toId }, { $inc: { balance: 100 } }, { session });
    // withTransaction auto-commits on success, auto-aborts on error, and retries transient errors
  }, {
    readConcern: { level: 'snapshot' },
    writeConcern: { w: 'majority' }
  });
} finally {
  await session.endSession();
}

Transaction Scope and Collections

A MongoDB transaction can span multiple collections and databases within the same cluster (MongoDB 4.2+ for sharded clusters). You can read from one collection, update another, and insert into a third—all within a single atomic transaction. The only restriction is that you cannot create new collections or indexes inside a multi-document transaction; those DDL operations must happen outside transactions.

await session.withTransaction(async () => {
  const db = client.db('ecommerce');
  
  // Span multiple collections in one transaction
  await db.collection('inventory').updateOne(
    { productId: 'P1' }, { $inc: { stock: -qty } }, { session }
  );
  await db.collection('orders').insertOne(
    { productId: 'P1', qty, status: 'new', createdAt: new Date() }, { session }
  );
  await db.collection('customers').updateOne(
    { _id: customerId }, { $push: { orderHistory: orderId } }, { session }
  );
});

Transactions Require Replica Sets

Multi-document transactions require a replica set or sharded cluster—they do not work on a standalone MongoDB instance. On a standalone, the transaction API exists but calling startTransaction() throws an error. This means your local development setup should use a local replica set (e.g., via mongod --replSet rs0 or via Atlas free tier) if your application code uses transactions.

// Starting a local replica set for development:
// 1. Start mongod with replica set name
// mongod --replSet rs0 --port 27017 --dbpath /data/db

// 2. In mongosh, initiate the replica set:
// rs.initiate()

// Now transactions will work on localhost

Transaction Timeout and Limits

MongoDB enforces a 60-second maximum transaction lifetime by default (configurable via transactionLifetimeLimitSeconds). Transactions that run longer are automatically aborted. Additionally, transactions are capped to 16 MB of oplog space for write operations. Long-running transactions also hold locks and can degrade performance for concurrent operations, so keep transactions short and focused.

Full Transfer Example With Validation

Putting it all together: a complete, production-ready bank transfer function using withTransaction. It validates sufficient balance inside the transaction (ensuring no other writer could have drained the account between the check and the debit) and records an audit entry atomically. This pattern demonstrates all key transaction concepts.

async function transferFunds(client, fromId, toId, amount) {
  const session = client.startSession();
  try {
    await session.withTransaction(async () => {
      const accounts = client.db('bank').collection('accounts');
      const from = await accounts.findOne({ _id: fromId }, { session });
      
      if (!from || from.balance < amount) {
        throw new Error('Insufficient funds');
      }
      
      await accounts.updateOne({ _id: fromId }, { $inc: { balance: -amount } }, { session });
      await accounts.updateOne({ _id: toId }, { $inc: { balance: amount } }, { session });
      await client.db('bank').collection('auditLog').insertOne(
        { from: fromId, to: toId, amount, date: new Date(), type: 'transfer' }, { session }
      );
    });
    return { success: true };
  } finally {
    await session.endSession();
  }
}

Quick Check

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

Lesson Recap

In this lesson you learned: transactions require a ClientSession created with client.startSession(), every operation in the transaction must receive { session } to be included, and withTransaction() is the recommended helper because it handles retry logic and cleanup automatically. Next up we explore error handling and retry logic for transient transaction failures.

Często zadawane pytania

Czy lekcja „Uruchamianie sesji i transakcji obejmującej wiele dokumentów” jest bezpłatna?

Tak — pełny tekst „Uruchamianie sesji i transakcji obejmującej wiele dokumentów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu MongoDB Academy, przejdź na CoddyKit PRO. Kurs MongoDB Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Uruchamianie sesji i transakcji obejmującej wiele dokumentów”?

Nauczą się Państwo otwierać ClientSession, wykonywać wiele operacji w ramach startTransaction() oraz zatwierdzać lub wycofywać transakcję. Ćwiczysz MongoDB Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć MongoDB Academy?

Nie wymagamy żadnego doświadczenia. MongoDB Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Uruchamianie sesji i transakcji obejmującej wiele dokumentów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji MongoDB Academy?

Tak. Każda lekcja MongoDB Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Gwarancje ACID w rozproszonym magazynie dokumentów
  2. Uruchamianie sesji i transakcji obejmującej wiele dokumentów
  3. Obsługa błędów i logika ponawiania prób
  4. Aspekty wydajnościowe transakcji
← Powrót do MongoDB Academy