NAME
AmberDB::Transact - ACID-compliant transactions with Strict Two-Phase Locking (Strict 2PL) and undo journaling engine
SYNOPSIS
# Transaction operations are called directly on the AmberDB instance:
# 1. Start transaction
$adb->transact_start();
# 2. Perform atomic CRUD operations across multiple tables
$adb->modify_id("inventory_stock", $product_id, @updated_stock);
$adb->insert_id("orders_item", @order_item_record);
# 3. Finalize transaction (commits if clean, automatically rolls back on database errors)
my $res = $adb->transact_end();
if ($res->{status} eq 'commit') {
print "Transaction committed successfully (operations: $res->{ops})\n";
}
else {
warn "Transaction aborted and rolled back due to error: " . join(", ", map { $_->{message} } @{$res->{errors}});
}
# 4. Manual business-logic rollback (e.g. payment gateway declined or insufficient stock)
if ($payment_failed) {
$adb->transact_rollback();
}
# 5. Recovery of orphaned transactions from previous system/process crashes
$adb->transact_recover();DESCRIPTION
AmberDB::Transact provides ACID-compliant transaction undo logging, Strict Two-Phase Locking (Strict 2PL), and automated LIFO rollback for AmberDB. It records binary undo journal entries (txn/txn_*.txn) using ASCII record separators (0x1E) for atomic operations across base database files (.db), soft-delete archives (.del), user audit histories (.aut), and all associated index files (.inx, .src, .fld, .fac, .srt, .rwt, .jinx, .jsrc, .jfld).
Transactions maintain process ownership via exclusive non-blocking flock on journal files, hold record-level write locks throughout the transaction lifecycle, and guarantee crash durability through IO::Handle buffer flushing, optional filesystem sync (txn_sync => 1), and automated orphaned journal recovery (transact_recover).
Inheritance Note: AmberDB inherits from AmberDB::Transact via use parent. All transaction methods documented below are invoked directly on $adb.
BATCH ETL OPERATIONS VS BUSINESS TRANSACTIONS
Transaction undo logging is designed for single-record business operations (insert_id, modify_id, delete_id) where inter-record atomicity and consistency are required. Bulk batch methods (insert_list, modify_list, delete_list) are optimized for high-throughput data ingestion (e.g. XML/JSON ETL imports) and purposely bypass the transaction journal for maximum I/O performance. If transactional atomicity is required for bulk records, execute individual CRUD methods in a loop enclosed within transact_start() and transact_end().
METHODS
transact_start()
Starts a new transaction. Creates an undo journal file under dbstore/txn/, acquires an exclusive non-blocking lock, and initializes the transaction state. Also triggers transact_recover to clean up any orphaned journals from previous crashes.
my $ok = $adb->transact_start();transact_end()
Finalizes the active transaction. Evaluates error log for base database failures: =over 4 =item * If critical errors occurred: performs a full LIFO rollback of all modifications across base tables and indexes, clears caches, and unlinks the journal. Returns { status => "rollback", errors => [...] }. =item * If no critical errors occurred: commits the transaction (releases locks and unlinks journal). Returns { status => "commit", ops => $count }. =back
my $result = $adb->transact_end();transact_rollback()
Forces an immediate manual rollback of the active transaction regardless of whether database errors were logged. Reverts all modified records in reverse order (LIFO), restores index states, clears affected table caches, releases locks, and unlinks the journal file.
my $result = $adb->transact_rollback();transact_recover()
Scans the dbstore/txn/ directory for orphaned transaction journals left behind by crashed or killed processes. Uses non-blocking flock to safely identify dead processes without race conditions and rolls back uncommitted operations to restore consistency.
$adb->transact_recover();transact_error($context, $message)
Logs a context-aware error during transaction processing. Errors originating from base data tables will trigger an automatic rollback when transact_end() is called.
$adb->transact_error("order_processing", "Failed to update balance");AUTHOR
Maruf Cetin <marufcetin@gmail.com>
LICENSE AND COPYRIGHT
Copyright (C) 2026 Maruf Cetin.
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.