Revision history for AmberDB
5.25.1 2026-09-11
- [JOURNAL & TRANSACTION STANDARDIZATION] Extensionless Uniform Journaling:
* Standardized all transaction undo logs and RAM-disk write-behind queues under $dbase_dir/journal/ ($adb->journal_dir()).
* Removed legacy .txn extension; transaction journal files now follow the standard extensionless format dbstore/journal/txn_<timestamp>_<seq>_<pid> (Base.pm:481-488).
* Modernized transact_recover() to scan journal/ directory for txn_* files and extract process IDs via /[-_](\d+)$/ for deterministic crash recovery without race conditions.
* Added explicit transact_commit() method alias to transact_end() matching documented public API semantics.
* Cleaned out obsolete legacy 5-parameter signature fallback and 6-field journal format fallback in AmberDB::Base::Transact.
- [RAM-DISK TIER 4 WRITE-BEHIND JOURNALING] Explicit sync_ramdisk Queue:
* Renamed dirty sync queue from sync_events to sync_ramdisk for clear semantic clarity:
- Active Queue: dbstore/journal/sync_ramdisk
- Rotated Queue: dbstore/journal/sync_ramdisk_<timestamp>
* Updated AmberDB::Base::Ramdisk (ramdisk_mark_dirty, ramdisk_sync, ramdisk_sync_db_path) and AmberDB::Base (journal_slot, journal_scan) to reflect sync_ramdisk naming.
* Synchronized background daemon engine (bin/amberdb_daemon.pl) and unit test suites (t/amberdb_ramdisk_tiers.t, t/amberdb_journal.t).
- [MODERN COMMAND LINE INTERFACE & NATURAL QUERY PARSER]
* Implemented unified bin/amberdb_cli.pl with bin/amberdb (POSIX shell) and bin/amberdb.bat (Windows CMD) wrappers.
* Natural positional query signatures:
- amberdb read <table> <id> (read_id)
- amberdb read <table> all [offset] [limit] [modifiers] (read_all)
- amberdb search <table> <query> [offset] [limit] [modifiers] (search_table)
- amberdb fetch <table> <block> <value> (field_fetch)
- amberdb count <table>, amberdb info <table>, amberdb status, amberdb ping
* Dual execution model: direct stateless execution against database without background session side-effects, and isolated session management via 4-digit numeric tokens (connect, disconnect, config, path, attr).
* Trailing output format (json, pretty, tsv, dumper, table, raw) and elapsed execution time (time, time=1, --time) keywords.
* Preserved clean machine-readable JSON output by rendering execution time metrics as an independent footer line.
* Completely eliminated redundant %cli_path and %cli_cfg hashes in CLI, directly utilizing $adb->path() and $adb->config().
* Added full CLI test suite in t/amberdb_cli.t (100% pass) and updated wiki documentation (TR-Guide-CLI.md, Guide-CLI.md, bin/commands.md).
5.25.0 2026-09-10
- [CORE ENGINE MODULARIZATION & NAMESPACE RESTRUCTURING] Grouped Internal Engine Modules Under AmberDB::Base::*:
* Migrated and reorganized core engine components into AmberDB::Base namespace:
- AmberDB::Base::Encoder (Serialization, multi-era format decoding, binary index packing)
- AmberDB::Base::Schema (Schema definition, table_info, table_attr, field type system)
- AmberDB::Base::Ramdisk (Physical RAM-disk Linux tmpfs, macOS APFS, Windows ImDisk file acceleration)
- AmberDB::Base::Cache (In-memory L1 process cache and staging disk buffer)
- AmberDB::Base::Index (Field indexing, foreign keys, operators)
- AmberDB::Base::Facet (Faceted search and category aggregation)
- AmberDB::Base::Junk (Multi-tiered soft-delete and junk rule processing)
- AmberDB::Base::Transact (WAL transaction engine and atomic journaling)
* Excluded entire lib/AmberDB/Base/ directory and AmberDB::Base namespace from CPAN indexing in Makefile.PL (no_index), keeping MetaCPAN documentation clean and focused on public standalone interfaces.
* Consolidated public submodule architecture in AmberDB POD to focus exclusively on standalone components (AmberDB::Date, AmberDB::Locale, AmberDB::Tools).
* Integrated ISO 4217 Currency Dictionary documentation into AmberDB::Locale and removed standalone POD from internal AmberDB::Locale::Currency to prevent separate CPAN indexing.
* Deprecated and removed unused legacy Amber::Util::String module; consolidated trim_space utility into AmberDB::Base.
- [TRANSPARENT PHYSICAL RAM-DISK ACCELERATION & CROSS-PLATFORM ORCHESTRATION]
* Cross-Platform Support (Linux, macOS, Windows): Standardized bin/ramdisk_* suite (ramdisk_amberdb.pl, ramdisk_windows.bat/ps1, ramdisk_macos.sh, ramdisk_linux.sh) with native support for Linux tmpfs, macOS APFS RAM-Disk (hdiutil), and Windows ImDisk with project namespace isolation.
* Global & Per-Table Acceleration: Supports global use_ramdisk => 1|2 in AmberDB->new with per-table overrides (use_ramdisk => 0|1|2|3) and lazy preloading on first table access.
* Volatile Pure RAM-Disk Mode (Tier 3 & ramdisk_ttl): Supports memory-only unindexed tables (use_ramdisk => 3, use_simple => 1) with configurable sliding time-to-live expiration (ramdisk_ttl, default 300s).
* Custom Storage Subfolder Organization (table_dir): Allows routing table and index files to dedicated subfolders (e.g. table_dir => 'orders') or directly to the database root (table_dir => '').
* Standardized Path & Environment Options (dbase_dir): Engine root storage path formalized with full runtime reflection and set_datadir migration.
* Standardized RAM-Disk Parameters: Replaced legacy cache_size and cache_dir with ramdisk_size and ramdisk_dir across constructor, config, and diagnostic reporting.
* Native File Extension Architecture: RAM-disk stores all database and index files with their native extensions (.db, .inx, .fld, .src, .fac, .unq, .slg), retiring proprietary .cache file formats.
* Unified ramdisk_setup([$tableid]): Consolidated environment validation, mount diagnostics, and deterministic table preloading into a single method ($adb->ramdisk_setup), superseding legacy cache_setup and cache_preload.
* Dedicated L1 Process Cache API: Replaced legacy cache_* routines with clean, dedicated get_cache and set_cache methods for in-memory L1 storage.
* Hardened Mount Detection: Validates symlinks/junctions (-l) and direct RAM paths with zero-subprocess /proc/mounts verification, auto-registered to $adb->config('ramdisk_mounted').
* Dual-Write & Transaction Safety: Real-time dual-write across index and data files with atomic Berkeley DB preloading and WAL rollback protection.
* Decoupled Engine Architecture: Separated AmberDB::Base::Ramdisk (physical file storage) from AmberDB::Base::Cache (in-memory L1 cache and staging buffers).
- [ENCODER & TOOLS UNIFICATION] Consolidated Multi-Era Text Decoding:
* Unified legacy and historical text decoding (v1 FlatDB, v2 \T, v3 <TAB>, v4 ARRAY/HASH) into tsv_decode in AmberDB::Base::Encoder.
* Streamlined AmberDB::Tools to directly delegate format detection and decoding to inherited $adb methods ($adb->detect_record_format and $adb->tsv_decode), eliminating redundant module requires.
- [OBJECT-RELATIONAL MAPPING & DATA HYDRATION] Native inflate and deflate Engine:
* AmberDB::inflate: High-performance transformation of flat storage arrays into schema-mapped hash structures:
- Named field key resolution based on table schema blocks (e.g. { id => 101, title => "Item", price => 500 }).
- Dynamic RDBM foreign relation resolution: resolves foreign IDs in 'display' mode (e.g. { 101 => "Samsung" }) or recursive 'full' mode.
- Repeating block support (repeat_start / type => 'repeat'): aggregates child items into an arrayref.
- Dual return formats: returns arrayref of records ('list') or primary-key indexed hashref ('hash') via { result => 'hash' }.
- Schemaless fallback: returns raw array reference safely when no schema blocks are defined.
- Transparently integrated with read_id, read_all, field_fetch, and search_table via { inflate => ... } or string "inflate".
* AmberDB::deflate: Inverse transformation of structured hashrefs into schema-ordered arrays:
- Accepts single hashref, arrayref of hashrefs, list of hashrefs, or hash-of-hashes.
- Re-encodes foreign relation hashes back into comma-separated ID lists.
- Automatically populates repeating child blocks and synchronizes summary repeat_ids fields.
- Transparently integrated with insert_id, modify_id, and insert_list for hash-based CRUD operations.
- [PARTIAL RECORD UPDATES & GRANULAR FIELD OPERATIONS] Direct Field Mutation:
* update_field($table, $id, ...): Updates a single block value or repeating child item without full record rewrite:
- Fixed schema blocks: accepts symbolic block name (e.g. "price") or numeric block index (e.g. 2).
- Repeating items: supports updating child items via id => $id, $item or pos => $idx, $item.
- Validates and normalizes field types via enc_field.
- Diff no-op guard: returns immediately if field value is unchanged.
- Clearing/reset: accepts undef or "" to reset field values according to schema type (e.g. 0 for numeric).
- Safety guard: prevents modification of primary key ID (block 0).
- Full transactional consistency, Strict 2PL locking, L1 cache invalidation, and index update (search, match, facet, unique, sort, slug).
* insert_field($table, $id, $item, %opts): Inserts a child item into repeating blocks (repeat_start):
- Default append to end or positional insertion via pos => $idx (e.g. pos => 0 to prepend).
- Duplicate child item ID protection: prevents duplicate entries if child ID already exists.
- Automatically synchronizes summary repeat_ids fields.
* delete_field($table, $id, %opts): Safely removes a child item from repeat blocks:
- Mandatory explicit targeting: strictly requires id => $item_id or pos => $idx (eliminating ambiguity and collision between child IDs and block/item position indexes; bare numbers and arbitrary keys are rejected).
- Guard against deleting fixed schema blocks (< repeat_start).
- Automatically synchronizes summary repeat_ids fields.
* Low-level binary primitives: Added bin_mod and bin_del for granular manipulation of 8-byte packed binary buffers.
- [3-STREAM DUAL-TIER JUNK INDEXING ARCHITECTURE]
* Separated indexing into three distinct streams: Base (all records without prefix), Tier A (A: prefix, active records), and Tier B (B: prefix, junk/passive records).
* Replaced legacy asymmetric j: prefix with clean, symmetric A: and B: tiers.
* Supports query modes A, B, AB, BA, and ALL/none, with query-level jnktype override and dynamic table_attr toggle.
* Hardened transaction engine (WAL) rollback to maintain full 3-stream parity across Base, Tier A, and Tier B streams on insert, modify, and delete rollbacks.
* Unified indexing methods (records_add/del, match_*, search_*, sort_*) with a direct $tier parameter, eliminating separate duplicate methods without extra helpers or aliases.
* Renamed re-indexing script from bin/convert_dbstore.pl to bin/dbstore_reindex.pl for clarity.
* NOTE: Upgrading to this architecture requires re-indexing existing tables via bin/dbstore_reindex.pl or AmberDB::Tools->set_index.
- [BUG FIXES] Index Read Order & Direction:
* Fixed read order regression in read_all, field_fetch, and table_keys: restored default descending order (N..1, newest records first) to fix pagination drift.
* Added explicit dir => 'asc'|'desc' (alias order) option across read_all and field_fetch.
- [STORAGE MIGRATION & UPGRADE INSTRUCTIONS FOR EXISTING DEPLOYMENTS]
* Upgrading Existing Installations (< 5.25.0):
- Existing deployments upgrading from prior AmberDB releases must migrate their database storage layout and formats using the unified amberdb_setup.pl utility:
perl bin/amberdb_setup.pl --action=update-storage --dbase_dir=<path_to_dbase> --all
Or check and apply full engine + storage updates:
perl bin/amberdb_setup.pl --action=update --dbase_dir=<path_to_dbase>
- Automated Migration Stages in v5.25.0:
* Directory Migration (tables/ -> table/): Automatically merges files into standard 'table/' layout. If 'table/' already exists, files are merged safely; any name collisions are preserved and renamed with a date stamp (<basename>_<YYYY-MM-DD>.<ext>, e.g., catalog_product_2026-08-25.db, catalog_product_2026-08-25.inx) with secondary collision counters (_1, _2) to guarantee zero data loss.
* Binary Record Format (ABR v5): Upgrades all legacy table formats (TSV, FlatDB, HTML entities) to native 5-byte magic packed binary records.
* Secondary Index Rebuilding: Reconstructs and repacks all secondary indexes (.inx, .fld, .unq, .fac, .slg, .srt) for the dual-tier 3-stream indexing architecture.
* Standard Directory Layout: Synchronizes and verifies all required runtime directories (table, schema, journal, lock, session, config, ramdisk) and stamps config/storage_version.json with 5.25.0.
- [TEST SUITE & COMPATIBILITY]
* Added dedicated test suite t/amberdb_migrate_5_25_conflict.t covering tables/ to table/ migration, date-stamped conflict resolution, and amberdb_setup.pl update-storage execution.
* Added dedicated test suite t/amberdb_junk_tiered.t covering 3-stream dual-tier indexing (CRUD, transitions, hybrid modes, Tools rebuild).
* Added dedicated test suite t/amberdb_read_order.t verifying default descending (N..1) read order and explicit direction flags.
* Added dedicated test suite t/amberdb_inflate_deflate.t covering single/batch inflate, deflate, RDBM resolution, and repeat blocks.
* Added dedicated test suite t/amberdb_field_ops.t covering update_field, insert_field, delete_field, and constraint guards.
* Added dedicated test suite xt/amberdb_ramdisk.t covering physical RAM-disk operations, isolated under author tests (xt/) to ensure standard installation tests pass without pre-mounted RAM-disk filesystems.
* Added dedicated test suite t/amberdb_schema_types.t covering all 9 schema types and type conversions.
* Refactored t/amberdb_cache.t to comprehensively test L1 in-memory caching and persistent staging buffers.
* Added default language ('gb') verification tests in t/amberdb_encapsulation.t and t/amberdb-locale_09_gb.t.
* 100% test pass rate across all 57 standard installation test files (534 assertions) and extended author test suite (xt/).
5.24.1 2026-09-05
- Standardized 'offset' pagination parameter with backward-compatible 'start' alias (read_all, field_fetch, search_table, field_filter, bin_decode, bin_crop, facet_menu).
- Added 'update_id' and 'update_list' method aliases for modify_id and modify_list.
- Fixed CPAN POD parsing error by adding =encoding utf8 to AmberDB::Locale.
- Globalized POD documentation: converted code examples in non-locale modules to standard English ASCII.
- Fixed POD list syntax in AmberDB::Base and eliminated whitespace warning in AmberDB.pm.
- Added t/amberdb_offset_update_alias.t unit test suite.
5.24.0 2026-09-05
- [BINARY RECORD SERIALIZATION ARCHITECTURE (ABR v5)] Native Pure Perl Binary Serialization:
* Introduced high-performance native pure Perl binary record serialization format (ABR v5 / Format 5) replacing legacy delimiter and regex text serialization (db_encode / db_decode), aligning format versioning with historical eras (v1: 2003 FlatDB, v2: 2005 \T, v3: 2021 <TAB>, v4: 2026 HTML entities, v5: 2026 ABR Binary).
* Zero CPAN Dependencies: Built strictly on core built-in Perl primitives (pack, unpack, substr, vec), completely eliminating version brittleness and security vulnerabilities associated with external serializers like Storable.
* Magic Header Architecture: Prefixes binary records with a 5-byte magic sequence (\x00ABR\x05); null-byte prefix guarantees zero collision with legacy plain text or data strings.
* Schema Type Coverage: Transparently maps all 9 AmberDB schema types into 1-byte typed nodes: UNDEF (0x00), SCALAR_RAW (0x01), SCALAR_UTF8 (0x02, via lossless utf8::encode/decode), ARRAY (0x03, 16-bit Big-Endian count), and HASH (0x04, 16-bit Big-Endian count).
* Nested Data Structures: Fully supports arbitrarily nested arrays, hashes, and repeat blocks with strict recursion depth guarding ($depth <= 32) to prevent stack overflow or circular reference hangs.
* Transparent Legacy Fallback: db_decode automatically falls back to _db_decode_legacy for non-ABR records, allowing mixed-version legacy tables to operate without downtime.
* Benchmarks: Achieves ~130,000 encodes/sec (+150% faster) and ~69,000 decodes/sec (+64% faster) on flat records; achieves ~4,300 decodes/sec (+35% faster) on complex deeply nested multi-level records.
- [BINARY INDEX ARCHITECTURE REFACTORING] Complete Migration of All Indexes to 8-Byte Packed Binary Buffers:
* Migrated all secondary index subsystems (.inx, .fld, .src, .fac, .slg, and Tier B Junk .jinx, .jfld, .jsrc) to pure 8-byte fixed-width packed binary buffers (pack "Q>", unpack "(Q>)*").
* Core Binary Primitives in AmberDB::Base: Implemented bin_add, bin_punch, bin_sort, bin_find, and bin_count operating directly on raw byte buffers via substr() and memory-aligned index(), achieving C-level execution speed.
* High-Level Cleanup: Completely eradicated high-level Perl array/hash manipulations (array_nodup, array_punch) from the core engine indexing path.
* Consolidated Pre-Sorted Indexing: Standalone .srt files are formally deprecated and eliminated; sort indexes are directly maintained inside .inx.
* Direct 64-bit Uint Indexing: Non-foreign key numeric fields in .fld bypass synthetic dictionary ID generation, indexing pure 64-bit unsigned integers directly into binary keys.
* Batch Foreign Key Pre-Fetching: Integrated batch RDBM ID pre-fetching in search and junk indexing pipelines, reducing disk I/O overhead to zero during keyword tokenization.
- [LEGACY TABLE MIGRATION & RECONSTRUCTION ENGINE] Automated update_table & update_all in AmberDB::Tools:
* Multi-Era Format Detection: Implemented _detect_record_format and decode_legacy_record recognizing and decoding all historical formats across AmberDB history: 2003 FlatDB (v1), 2004-2006 \T arrays (v2), 2019-2025 <TAB0>..<TAB3> hierarchical tabs (v3), 2026 HTML entities (v4), and modern ABR v5 (v5).
* Automated Timestamped Backups: Automatically backs up migrating tables as <table_name>-v<detected_ver>-<YYYY-MMDD>.db prior to rewriting.
* Authoritative Data Preservation:
- .unq (Unique & Synonym Dictionary): Identified as non-reconstructible authoritative master data; strictly exempted from derived index cleanup, preserved live, and snapshot-copied to <table_name>-v<ver>-<date>.unq.
- .del (Soft-Deleted Records Archive): Detected via exist_table($table, 'del'), backed up, and all archived records migrated to ABR v5.
- .aut (Audit Trail Log): Detected via exist_table($table, 'aut'), backed up, and user modification history migrated to ABR v5.
- .cnt (Read Counter): Detected via exist_table($table, 'cnt'), backed up, and live counter state preserved.
* Clean Re-indexing via insert_list: Cleans up all derived and legacy indexes (qw(inx src fld fac slg srt jinx jfld jsrc)) and rebuilds table data and indexes atomically through $adb->insert_list.
- [COMMAND LINE UTILITY] Automated Migration Script (bin/update_tables.pl):
* Added CLI migration script bin/update_tables.pl supporting --all, --table=<names>, --dbase=<dir>, --force, and --help options.
* Provides granular per-table progress reporting and comprehensive post-migration summary (tables processed, upgraded, already up-to-date, record counts, and companion file backups).
- [TRANSACTION SAFETY, SEARCH & CSV COMPATIBILITY]
* Transact Journal Escaping: Escaped \n, \r, \x1e, and \\ in binary record payloads logged to .txn journals, preventing binary length bytes from splitting WAL records or corrupting field boundaries.
* CSV Line Preservation: In tie2csv and vacuum, exported CSV records using _db_encode_legacy so exported files remain clean single-line human-readable text.
* Unindexed Search Word Extraction: Fixed search_table in unindexed mode to decode record fields before passing them to get_words, preventing binary length bytes from corrupting search tokens.
- [QUERY ENGINE & INDEX PERFORMANCE OPTIMIZATIONS] Adaptive Binary Intersect & Pure-Index Candidate Filtering:
* Adaptive Binary Search Pruning (bin_crop): Introduced dynamic thresholding between XS unpack probing and 8-byte aligned O(log N) binary search (substr). For massive posting lists (e.g. 600K records), eliminates huge Perl scalar allocations and byte-alignment collision issues, dropping multi-field pruning from 4.1 ms to 0.058 ms (58 us).
* Pure-Index Candidate Probing (search_table): Refactored multi-value/range filtering (e.g. 27-year date intervals) to evaluate candidate IDs directly against sorted 8-byte aligned index buffers via binary search, completely eliminating slow inverted unioning, zero .db reads, and zero massive 50,000-element Perl hash allocations.
* Batch Unindexed Fallback: Replaced iterative table_readid loops in unindexed search fallbacks with single-pass read_list batching, eliminating repetitive open/close file descriptor syscalls.
- [TEST COVERAGE & PACKAGING]
* Added comprehensive test suite t/amberdb_update_table.t covering multi-era format decoding, update_table migration, backup naming, .del/.aut/.cnt/.unq handling, and update_all batch discovery.
* Updated MANIFEST to include bin/update_tables.pl and new test suites.
* All 47 test files (440 assertions) passing with 100% success rate.
5.23.2 2026-09-03
- [LOCALE ENGINE & MULTILINGUAL ARCHITECTURE] 10th Language - Global Base (gb) and Default Locale:
* Introduced Global Base (gb) as the 10th supported language and new universal default/fallback locale (replacing en).
* Implemented comprehensive multilingual Latin character preservation in alphabet_chars across European, Turkish, Nordic, French, German, Spanish, and Slavic-Latin alphabets.
* Added cross-lingual, accent-tolerant search regex mapping (regex_map) matching accented and unaccented variations (e.g. cafe matches café, munchen matches münchen, seker matches şeker).
* Implemented canonical accent folding in accent_map for high-recall inverted search indexing (.src).
* Added lossless Unicode ligature conversion in ascii_map (ß->ss, æ->ae, œ->oe, ı->i, ø->o, ł->l, đ->d, ð->d, þ->th, ə->e) for clean URL slug and ASCII ID generation.
* Configured international English numbering, date formatting, and ISO standard decimal/group separators.
* Added language aliases: 'gb', 'global', 'gl', 'universal', 'uni', 'gb_base'.
* Added dedicated test coverage in t/amberdb-locale_09_gb.t.
- [TRANSACTION ARCHITECTURE & API REFINEMENT] Pure File-Path Error Model and Operational Rollback:
* Refactored transact_error($file_path, $message) to exclusively accept physical file paths; eliminated artificial "transaction" and "system" string contexts.
* Simplified table identification via single exact regex /([^\/\\:]+)\.$db_ext$/: directly extracts table ID and inspects schema no_transact attribute; non-db extensions (.inx, .src, .fld, .fac, .slg, .aut, .del, .txn) never trigger rollback (no_rollback = 1).
* Added immediate early return in transact_error if $file_path is undefined or empty.
* Established strict API role separation: application code directly invokes transact_rollback() for business logic cancellations (insufficient stock, credit limits, validation aborts) and unexpected eval exceptions; transact_error is reserved for internal physical storage/write safety.
* Unified legacy is_index and is_no_transact flags into single no_rollback attribute.
* Restructured insert_id to strictly validate mandatory $tableid at entry prior to resolving table paths, with proper ref guard for $rid.
5.23.1 2026-09-02
- [DISTRIBUTION & METADATA] Unified Versioning and MetaCPAN Curation:
* Unified $VERSION across all internal and standalone modules to 5.23.1 for consistent release identification and stack-trace debugging.
* Added no_index -> file specification in Makefile.PL for internal engine modules (Base, Cache, Index, Transact, Locale::Currency), curating the MetaCPAN release page to highlight the 6 public standalone modules.
* Excluded wiki/ documentation directory from CPAN distribution package (via MANIFEST.SKIP), reducing tarball size by ~30% and eliminating 246 redundant packaging entries.
* Updated main AmberDB abstract to "High-performance embedded NoSQL database engine for Perl".
5.23.0 2026-09-02
- [ARCHITECTURE & ID SIMPLIFICATION] Pure 64-bit Binary Engine & Deprecation of 8-Byte ASCII IDs:
* Deprecated 8-byte ASCII IDs (a8) across binary index structures in favor of pure 64-bit Big-Endian unsigned integer packing (Q>*), guaranteeing O(1) binary slicing with fixed 8-byte record strides.
* Simplified bin_encode() and bin_decode() by removing fragile \0 byte auto-detection and string unpacking heuristics.
* Removed legacy id_type schema attribute across all modules and test suites; standard relational tables strictly enforce positive integer numeric IDs.
- [STORAGE & PER-TABLE SIMPLE MODE] Hybrid Multi-Model Architecture with use_simple => 1:
* Introduced per-table use_simple => 1 attribute allowing key-value tables with arbitrary string keys up to 255 bytes (UUIDs, session tokens, emails, slugs, etc.) alongside standard relational tables.
* Preserved canonical physical table path ($dbase_dir/table/$table.db) for use_simple tables in standard database mode.
* Selective schema sanitization: tables with use_simple => 1 strip indexing, columnar, and caching definitions (blocks, match_block, search_block, facet_block, sort_block, record_index, use_cache, cache_ttl) to achieve zero index/cache I/O overhead while preserving behavioral features (keep_deleted, force, no_transact, no_backup, use_menu, log_owner).
* Enabled keep_deleted => 1 archiving (.del) on use_simple tables.
- [RDBM & INTEGRITY] Foreign Key and Cross-Table Isolation:
* Prohibited standard relational tables from binding foreign keys (RDBM) to use_simple tables in rdbm_target() and _resolve_field_value().
- [TESTS & VERIFICATION] Dedicated Test Coverage:
* Added comprehensive test suite t/amberdb_table_use_simple.t verifying arbitrary string keys, schema sanitization, zero index file creation, keep_deleted archiving, and RDBM isolation.
* Cleaned up legacy id_type occurrences across all 41 test files and concurrency stress tests (xt/amberdb_concurrency_stress.t).
- [DISTRIBUTION & METADATA] Decoupled Internal Module Versions and CPAN no_index:
* Stripped redundant $VERSION definitions from 15 internal/engine-only modules (Base, Cache, Transact, Index, Index::Facet, Index::Junk, Locale::Currency, Locale::Lang::*) to streamline release maintenance.
* Retained explicit $VERSION in public, standalone modules (AmberDB, AmberDB::Array, AmberDB::Date, AmberDB::Locale, Amber::Util::String, AmberDB::Tools).
* Added comprehensive META_MERGE no_index configuration in Makefile.PL covering internal directories, namespaces, and packages.
- [DATA STRUCTURES & UTILITIES] Non-Destructive hash_diff in AmberDB::Array:
* Implemented hash_diff($hash1, $hash2) in AmberDB::Array with safe shallow copying, ensuring input hash structures are never mutated.
* Removed legacy internal _hash_diff from AmberDB::Tools and switched to $adb->hash_diff directly.
* Added unit test coverage for hash_diff in t/amberdb_array.t.
5.22.2 2026-09-01
- [CROSS-PLATFORM & CI] Universal GitHub Actions CI Matrix:
* Configured multi-platform CI matrix testing on Linux (ubuntu-latest), macOS (macos-latest), and Windows (windows-latest) across Perl 5.16 through 5.40.
* Configured official Strawberry Perl distribution in CI for native Berkeley DB / DB_File binary compatibility and prevented Git Bash PATH collisions.
- [STORAGE & TRANSACTIONS] Safe Directory Scanner and Windows File Sharing:
* Introduced dir_files($dir, [$pattern], [%opts]) helper method in AmberDB::Base for cross-platform, safe file discovery supporting wildcards (*.db, txn_*.txn) and compiled regular expressions (qr/../).
* Refactored AmberDB::Transact and AmberDB::Tools (dir_tables, all_tables, del_table) to use dir_files, completely removing fragile glob usage.
* Fixed Windows NTFS file sharing collision in transact_recover: journal lines are now read directly from open locked handles, preventing secondary open permission denied errors.
- [TESTS & STABILITY] Test Concurrency and Monotonic Sequence:
* Hardened t/amberdb_transact.t orphan recovery subtest to use strictly monotonic table_autoid record IDs (65) and authentic transaction lifecycle simulation.
* Guaranteed complete handle and lock cleanup with $adb->close_all() in crash recovery test scenarios.
5.22.1 2026-09-01
- [DOCS] Documentation and Synopsis Fixes:
* Fixed synopsis and API example signatures across documentation and POD.
* Updated README.md installation instructions with streamlined CPAN/cpanm cross-platform support.
* Fixed character encoding and wide-character warnings in test suite schemas.
5.22.0 2026-08-31
- [REFACTOR] Codebase Cleanliness:
* Removed redundant single-line helper is_rdbm_block() in favor of direct rdbm_target() calls across AmberDB::Index, AmberDB::Index::Junk, and AmberDB::Tools.
- [RDBM & INTEGRITY] Hardened Foreign Table Auto-Registration in field_to_list():
* Replaced decoupled table_autoid() and recs_put() sequence with atomic insert_id($target_table, 0, @record) to prevent ID race conditions.
* Corrected foreign record column alignment so auto-registered values are accurately placed at block index $target_blk rather than hardcoded column 1.
* Guaranteed that foreign table primary indexes (.inx) and secondary indexes (.unq, .src, .fac, .slg) are fully and consistently constructed upon auto-registration.
- [SECURITY & VALIDATION] Universal ID Verification and Simple Mode Key Sanitization:
* Eliminated opt-in config('id_check') requirement: every schema table now strictly enforces its schema id_type (positive integers for num, safe 8-byte chars for ascii).
* Enforced scalar ID requirement: any reference (ARRAY ref, HASH ref, etc.) passed as a record ID is strictly rejected across all modes.
* Introduced Safe Key Sanitization in Simple Mode: automatically trims leading/trailing whitespace, strictly rejects NUL bytes (\0) and control characters (\r, \n, \t, \x00-\x1F, \x7F) that corrupt Berkeley DB or CSV backups, and enforces a maximum key length of 255 bytes.
* Integrated unconditional id_check across table_autoid(), read_id(), modify_id(), delete_id(), and exist_id().
- [REFACTOR] Terminology and Codebase Refactoring: SEO -> Slug:
* Completely replaced SEO terminology with Slug across the entire codebase, test suite, and documentation without legacy aliases:
- Renamed methods: set_seourl() -> set_slug(), get_seourl() -> get_slug().
- Renamed schema attributes: seo_block -> slug_block, seo_max_len -> slug_max_len.
* Renamed test suite t/amberdb_seo_facet_bulk.t to t/amberdb_slug_facet_bulk.t.
- [STORAGE] Standardized URL Slug Map File Extension: .rwt -> .slg:
* Renamed binary slug map files from _0.rwt / _1.rwt to _0.slg (ID -> Slug) and _1.slg (Slug -> ID) across AmberDB, Index, Transact, and Tools.
* Updated Tools->set_index() to reconstruct .slg files with zero data loss.
- [DOCS] Caching Terminology Unification:
* Completely removed deprecated L1/L2 caching terminology from all documentation and POD.
* Standardized on unified "Shared RAM-Disk (tmpfs / ImDisk) Cache" architecture.
- [TESTS & CONCURRENCY] Cross-Platform Multi-Process Concurrency Stress Testing:
* Upgraded xt/amberdb_concurrency_stress.t to an OS-aware unified architecture supporting both Linux (POSIX fork+exec) and Windows (independent asynchronous perl.exe processes).
* Ensures full operating system-level flock(LOCK_EX) lock isolation on Windows without CRT/pseudo-fork thread contention.
* Comprehensive validation across 5 concurrency scenarios:
1. Multi-worker parallel writes with secondary index synchronization (.inx, .fld, .src, .fac, .srt, .slg).
2. Interleaved concurrent reads and writes without deadlocks or corruption.
3. Concurrent independent transactions with simulated mid-operation process crashes and orphan recovery (transact_recover).
4. High-concurrency duplicate title insertion verifying deterministic URL slug collision resolution and 100% bidirectional bijection.
5. Shared record inventory decrements using record-level locks (flock_open / flock_close).
- Added Section 7.8 ("Multi-Process Concurrency, Lock Isolation, and Stress Verification") to Turkish and English documentation.
- Updated README.md with concurrency stress testing instructions.
5.21.1 2026-08-29
- Fixed read_id return signature across documentation examples to consistently return array format.
- Streamlined transaction workflow documentation to use transact_error() for business validations with automatic commit/rollback in transact_end().
- Clarified field_fetch return signatures in English documentation to reflect full record retrieval.
- Declared missing core dependencies (Archive::Tar, Digest::SHA, JSON::PP, Hash::Util) in Makefile.PL and cpanfile.
5.21.0 2026-08-28
- Fixed schema cache poisoning in restore() and hardened dbase_info()/table_info() against caching empty parse results.
- Standardized instance variable naming across codebase, test suites, and documentation to $adb (AmberDB Handle):
* Introduced $adb->config() method supporting scalar get, defensive copy bulk get, and side-effect hook execution (locale reloading, path cache invalidation).
* Introduced $adb->path() method for standardized path retrieval and modification across core modules and scripts.
* Enhanced $adb->table_attr() with unified getter/setter and automatic path refresh on schema changes (year, section, lang).
* Protected $adb->table_info() by returning shallow copies to prevent external reference leaking and unauthorized in-memory state mutations.
* Refactored all internal core modules (lib/AmberDB.pm, lib/AmberDB/Base.pm, lib/AmberDB/Tools.pm, lib/AmberDB/Transact.pm, lib/AmberDB/Cache.pm, lib/AmberDB/Index/Junk.pm) to interact strictly through accessor methods ($adb->config, $adb->path, $adb->table_attr, $adb->table_info) eliminating raw hash accesses.
* Enforced restricted hash key access via Hash::Util::lock_keys with private internal naming (_cfg, _path, _table, _dbase, _cache, _db, _txn) and locked container references (Hash::Util::lock_value) against typo/unauthorized overwrites.
* Added comprehensive unit test suite t/amberdb_encapsulation.t covering all 10 encapsulation scenarios.
- [MIGRATION NOTICE / BREAKING CHANGE] Standardized schema terminology across the entire codebase and directory layout:
* UPGRADE ACTION REQUIRED: Existing projects must rename their physical 'dbstore/scheme/' directory to 'dbstore/schema/'.
* Updated RAM-disk setup scripts (setup_ramdisk.sh, setup_ramdisk.ps1, setup_ramdisk.pl, setup_ramdisk.bat) to mount 'schema/'.
- Upgraded transaction engine specification to full ACID-Compliance with Strict Two-Phase Locking (Strict 2PL):
* Enforced Lock-Before-Write and Lock-Before-Read ordering across insert_id, modify_id, and delete_id for true serializable isolation.
* Introduced 'no_transact => 1' schema attribute and table_attr() support to exempt auxiliary tables from abort cascades while preserving LIFO rollback consistency.
- Added comprehensive ACID architectural guarantees section to documentation (README.md, Turkish and English User Guides).
- Clarified architectural distinction between high-throughput batch ETL imports and atomic business transactions.
- Standardized file open error diagnostics and OS-level reporting ($!) across all core modules:
* Added explicit OS error reporting ($!) to all open and tie failures in AmberDB, Base, Cache, Transact, and Tools.
* Replaced silent schema open failure in AmberDB::Base::table_write with diagnostic cluck and graceful return.
* Improved audit log error handling in AmberDB::auth_insert with cluck and record skipping.
- Redesigned 2-Pillar Disaster Recovery and Native Backup Architecture:
* Upgraded recs_back to continuous chronological time-series stream in 'backup/YYYY/YYYY-MM-DD.csv' eliminating folder clutter and ensuring zero-data-loss logging.
* Added Tools->dump() for creating portable, compressed '.amberdb' archives packaging schemas (schema/*.table, schema/*.dbase), authoritative data files (tables/*.db, tables/*.del, tables/*.aut, tables/*.cnt, tables/*_*.str), and cryptographic SHA-256 integrity manifests (excluding derived indexes).
* Preserved native physical directory layout (schema/ and tables/) in .amberdb archives for 1-to-1 extraction and portability.
* Added Tools->restore() with SHA-256 checksum verification, non-empty database safety checks, and automated deterministic binary index reconstruction via set_index.
* Enhanced Tools->all_tables() with dual scalar/list context (grouped hashref vs. flat list) and automated 4-digit year directory discovery (e.g. 2024/, 2025/, 2026/).
* Upgraded 'bin/convert_dbstore.pl' table discovery and added side-file reporting for .str string dictionaries alongside .del, .aut, and .cnt.
* Introduced CLI utility 'bin/amberdb_backup.pl' for command-line database dump and disaster recovery operations.
* Added comprehensive unit test suite t/amberdb_backup.t covering WAL streaming, .amberdb archiving, .dbase/.str preservation, and full database restore.
- Updated POD documentation across AmberDB, AmberDB::Transact, and AmberDB::Tools modules.
5.02 2026-08-25
- Initial public release prepared for CPAN and GitHub.
- High-performance Berkeley DB (DB_File) flat-file database engine.
- Packed 8-byte binary indexing pipeline for O(1) substr slicing.
- High-speed index-assisted full-text search with phonetic and language normalization.
- Tiered indexing (Active, Junk/Archived, and Hybrid AB/BA query modes).
- Multi-dimensional Columnar Facet indexing (.fac) with high-efficiency bitsets.
- Undo-journal transaction engine (transact_start, transact_end, transact_rollback) with automatic LIFO rollback.
- Multi-granularity concurrency control (table-level and record-level flock).
- Multilingual locale engine supporting 9 languages (en, tr, de, fr, es, ja, ru, ar, az) with Turkish dotless/dotted 'i' rules, case folding, and number/currency formatting.
- Cross-platform RAM-Disk helper and binary index converter CLI tools.
- Comprehensive test suite covering 37 test suites.