/ 
AmberDB-5.02
/ AmberDB::Transact

NAME

AmberDB::Transact - Transaction and Undo Journaling Engine for AmberDB

SYNOPSIS

use parent qw(
    ...
    AmberDB::Transact
    ...
);

# Start transaction
$dbp->transact_start();

# Perform DB operations
$dbp->insert_id("table_name", @record);
$dbp->modify_id("table_name", $rid, @record);

# Finalize transaction (commit if clean, auto-rollback if base errors occurred)
my $res = $dbp->transact_end();
if ($res->{status} eq 'commit') {
    print "Committed successfully!\n";
}

# Manual rollback driven by business logic
$dbp->transact_rollback();

# Recover orphaned transactions from crashed processes
$dbp->transact_recover();

DESCRIPTION

AmberDB::Transact provides ACID-like transaction logging and rollback functionality for AmberDB. It records undo journal entries (.txn) using ASCII record separators for atomic operations across base database files (.db) and all associated index files (.inx, .src, .fld, .fac, .rwt).

Transactions maintain process ownership via exclusive non-blocking flock on journal files and guarantee crash durability through IO::Handle buffer flushing and optional fsync (txn_sync => 1).

CAVEATS AND LIMITATIONS

Transaction undo logging (_txn_log) is only executed for single-record CRUD operations (insert_id, modify_id, delete_id). Bulk batch methods (insert_list, modify_list, delete_list) perform direct batch processing for performance and do not write entries to the transaction journal. Consequently, changes made via bulk operations are not recorded in active transactions and cannot be rolled back by transact_rollback() or transact_end(). If atomicity and rollback capability are required, use single-record methods instead of bulk methods.

METHODS

transact_start()

Starts a new transaction by opening an undo log journal file in txn/ and acquiring an exclusive non-blocking flock. Automatically triggers orphan recovery.

transact_end()

Finalizes the active transaction. Evaluates error log for base database failures; if critical errors exist, it performs a full LIFO rollback. Releases lock and unlinks journal file. Returns a hash reference with status (commit or rollback).

transact_rollback()

Forces an immediate rollback of the active transaction regardless of error state. Releases lock and unlinks journal file.

transact_recover()

Scans txn/ directory for orphaned transaction journals from crashed processes. Uses non-blocking flock to safely identify dead processes without race conditions and rolls back uncommitted operations.

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.