PhoenixmlDb.Core

IReadTransaction

A read-only transaction that provides MVCC snapshot isolation over the database.

#IReadTransaction

Namespace: PhoenixmlDb.Core

A read-only transaction that provides MVCC snapshot isolation over the database.

A read transaction captures a frozen, point-in-time view of the database using MVCC (Multi-Version Concurrency Control). Once begun, the transaction sees a consistent snapshot — any concurrent writes by other threads or processes are invisible to it. This guarantees repeatable reads without locking.

Concurrency: Multiple read transactions can be active simultaneously, and they do not block writers. Read transactions are lightweight and non-blocking by design.

When to use explicit read transactions: Use a read transaction when you need to read multiple documents or run multiple queries with a consistent view. For example, reading a customer document and their related orders atomically ensures you don't see a partially-updated state.

When NOT to use: For single document reads or single queries, the convenience methods on IContainer (e.g., IContainer.GetDocumentAsync, IContainer.QueryAsync) handle transactions automatically and are simpler.

Important: Always dispose read transactions promptly. Long-lived read transactions prevent LMDB from reclaiming disk space used by older versions of data, which can cause the database file to grow indefinitely.

#Example

Read multiple documents with a consistent snapshot:

using var txn = db.BeginRead();
var customer = await txn.GetDocumentAsync(customersContainer.Id, "acme.xml");
var orders = txn.ListDocumentsAsync(ordersContainer.Id);

// Both reads see the same snapshot — no concurrent writes are visible
await foreach (var order in orders)
{
    Console.WriteLine($"Order: {order.Name}");
}
                                  

#Properties

#Methods

#GetDocumentAsync(PhoenixmlDb.Core.ContainerId,String,Threading.CancellationToken)

Gets a document by name within this transaction's snapshot.

Parameters:

• container — The container to look up the document in.

• name — The document name (case-sensitive).

• cancellationToken — Cancellation token.

Returns: The IDocument if found, or null if not found.

The returned document reflects the state at the time this transaction was begun, regardless of any concurrent modifications.

#ListDocumentsAsync(PhoenixmlDb.Core.ContainerId,Threading.CancellationToken)

Lists all documents in a container within this transaction's snapshot.

Parameters:

• container — The container to list documents from.

• cancellationToken — Cancellation token.

Returns: An async enumerable of DocumentInfo records.

#QueryAsync(PhoenixmlDb.Core.ContainerId,String,Collections.Generic.IReadOnlyDictionary<String,Object>,Threading.CancellationToken)

Executes an XQuery expression within this transaction's snapshot.

Parameters:

• container — The container to query against.

• xquery — The XQuery expression to execute.

• variables — Optional external variable bindings (keys without $ prefix).

• cancellationToken — Cancellation token.

Returns: An async enumerable yielding each item in the XQuery result sequence.

Exceptions:

• XQueryException — The query has a syntax error or runtime error.

The query sees only documents that existed at the time this transaction was begun. This ensures query results are consistent even if other threads are modifying the database.

#See also

• IDocumentDatabase.BeginRead

• IWriteTransaction