PhoenixmlDb.Core

IWriteTransaction

A read-write transaction providing full ACID guarantees for atomic multi-document operations.

#IWriteTransaction

Namespace: PhoenixmlDb.Core

A read-write transaction providing full ACID guarantees for atomic multi-document operations.

A write transaction inherits all read capabilities from IReadTransaction and adds the ability to insert, update, and delete documents. All mutations within a write transaction are buffered and become visible to other readers only after IWriteTransaction.CommitAsync is called.

Single-writer model: PhoenixmlDb follows LMDB's single-writer design — only one write transaction can be active at a time across all threads and processes accessing the same database. If another write transaction is in progress, acquiring a new one blocks (or times out, if using the timeout overload of IDocumentDatabase.BeginWriteAsync).

Commit or rollback: You must explicitly call IWriteTransaction.CommitAsync to persist changes or IWriteTransaction.RollbackAsync to discard them. If the transaction is disposed without committing, all changes are automatically rolled back — but relying on this for normal flow is discouraged; prefer explicit rollback for clarity.

Common use patterns:

  • Batch import: Insert many documents in a single transaction for atomicity and performance.

  • Read-modify-write: Read a document, transform it, and write it back within the same transaction.

  • Atomic multi-document updates: Update related documents together so readers see all-or-nothing.

#Example

Typical write transaction lifecycle — batch import with error handling:

csharp 
await using var txn = await db.BeginWriteAsync(TimeSpan.FromSeconds(10));
try
{
    foreach (var file in Directory.GetFiles("/data/imports/", "*.xml"))
    {
        var content = await File.ReadAllTextAsync(file);
        var name = $"imports/{Path.GetFileName(file)}";
        await txn.PutDocumentAsync(container.Id, name, content);
    }

    await txn.CommitAsync();
    Console.WriteLine("Import committed successfully.");
}
catch (Exception ex)
{
    await txn.RollbackAsync();
    Console.WriteLine($"Import rolled back: {ex.Message}");
}

#Methods

#CommitAsync(Threading.CancellationToken)

Commits all changes made within this transaction, making them permanently visible.

Parameters:

  • cancellationToken — Cancellation token.

Exceptions:

After a successful commit, all inserted, updated, and deleted documents become visible to new read transactions. The write lock is released, allowing other write transactions to proceed.

A commit is durable — once this method returns successfully, the changes survive process crashes and power failures (subject to LMDB's sync mode).

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

Deletes a document within this transaction.

Parameters:

  • container — The container holding the document.

  • name — The name of the document to delete.

  • cancellationToken — Cancellation token.

Returns: true if the document existed and was marked for deletion; false if not found.

The deletion is not visible to other readers until

is called.

#PutDocumentAsync(PhoenixmlDb.Core.ContainerId,String,String,PhoenixmlDb.Core.DocumentOptions,Threading.CancellationToken)

Inserts or updates a document within this transaction.

Parameters:

  • container — The target container.

  • name — Document name (URI-like identifier, case-sensitive).

  • content — The XML or JSON content to store.

  • options — Optional settings for content type, overwrite behavior, and metadata.

  • cancellationToken — Cancellation token.

Exceptions:

The document is buffered in the transaction and only becomes visible to other readers after

is called. If the transaction is rolled back, the document is discarded.

#RollbackAsync(Threading.CancellationToken)

Rolls back all changes made within this transaction, discarding them entirely.

Parameters:

  • cancellationToken — Cancellation token.

After rollback, the database is exactly as it was before the transaction began. The write lock is released, allowing other write transactions to proceed.

Disposing a write transaction without committing also rolls back, but calling IWriteTransaction.RollbackAsync explicitly is preferred for code clarity.

#SetMetadataAsync(PhoenixmlDb.Core.ContainerId,String,PhoenixmlDb.Xdm.XdmQName,PhoenixmlDb.Xdm.XdmValue,Threading.CancellationToken)

Sets a metadata value by explicit qualified name, within this transaction.

Parameters:

  • container — The container holding the document.

  • documentName — The name of the document to attach metadata to.

  • name — The fully qualified metadata name.

  • value — The metadata value.

  • cancellationToken — Cancellation token.

Exceptions:

Joins the caller's transaction; not visible until

.

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

Sets a metadata value in the container's default namespace, within this transaction.

Parameters:

  • container — The container holding the document.

  • documentName — The name of the document to attach metadata to.

  • name — The local metadata name, resolved against the container's default namespace.

  • value — The metadata value.

  • cancellationToken — Cancellation token.

Exceptions:

Unlike

, which opens and commits its own write transaction, this joins the caller's transaction — the write is not visible until

.

#SetMetadataAsync``1(PhoenixmlDb.Core.ContainerId,String,PhoenixmlDb.Core.Metadata.MetadataProperty<``0>,``0,Threading.CancellationToken)

Sets a typed metadata value within this transaction. The namespace and value type come from the property.

Type parameters:

  • T — The property's CLR value type.

Parameters:

  • container — The container holding the document.

  • documentName — The name of the document to attach metadata to.

  • descriptor — The metadata property descriptor.

  • value — The metadata value.

  • cancellationToken — Cancellation token.

Exceptions:

Joins the caller's transaction; not visible until

.

#See also