view release on metacpan or  search on metacpan

docs/index.md  view on Meta::CPAN

```perl
use strict;
use warnings;
use AmberDB;

# 1. Initialize Database Instance
my $adb = AmberDB->new(
    cfg  => { user => 'admin', language => 'en' },
    path => { dbase_dir => './dbstore' }
);

# 2. Define Record (Array-Based Document Structure)
my @product = (
    0,                          # [0] id (0 indicates auto-increment ID)
    "Wireless Headphones",      # [1] name
    149.99,                     # [2] price
    "Sony",                     # [3] brand
    "Electronics",              # [4] category
    { status => "In Stock" }    # [5] attributes (hash reference)
);

# 3. Insert Record
my $id = $product[0] = $adb->insert_id( "products", @product );

# 4. Read Record by ID
my @from_db = $adb->read_id( "products", $id );
print "Product: $from_db[1], Price: $from_db[2], Status: $from_db[5]->{status}\n";

# 5. Modify Record
$product[2] = 129.99; # Update price block
$adb->modify_id( "products", @product );

# 6. Full-Text Search
my @results = $adb->search_table( "products", "sony headphones" );
foreach my $p (@results) {
    print "ID: $p->[0] | Name: $p->[1] | Price: $p->[2]\n";
}

# 7. Delete Record
$adb->delete_id( "products", $id );
```

---

## âš¡ Core Architecture & Capabilities

### 1. JOIN-Free Hierarchical Records
Instead of distributing data across multiple normalized tables and reassembling via costly SQL `JOIN`s, AmberDB stores records as natural, nested array tuples (including sub-arrays and sub-hashes). This matches Perl's native data structures and deliv...

### 2. 64-Bit Big-Endian Binary Indexing
Primary and secondary indexes use fixed 8-byte packed Big-Endian unsigned integer buffers (`Q*`). This guarantees $O(1)$ binary slicing, zero string-unpacking heuristics, and sub-millisecond pagination even across datasets scaling into millions of ro...

### 3. ACID Transactions with Strict 2PL
Full multi-table transaction support with a disk-backed undo journal (`.txn`) and Strict Two-Phase Locking (Strict 2PL). Abnormal terminations trigger automatic LIFO rollbacks upon recovery.

### 4. High-Throughput Batch Ingestion
Bulk ETL methods (`insert_list`, `modify_list`, `delete_list`) open master tables once and merge indexes in a single pass, delivering 50x–100x higher throughput compared to single-record loops.

### 5. Multi-Tier Junk & Archiving
Active records (`.db`) are seamlessly segregated from historical or archived rows (`.jnk`), supporting unified single-pass queries (`jnktype => 'A' | 'B' | 'AB' | 'BA'`).

### 6. Faceted Category Filter Engine
Built-in columnar facet indexing (`.fac`) with bitwise set intersections and string dictionaries (`.str`) enables instant e-commerce filtering menus without external search appliances.

---

## 📊 Feature Comparison

| Capability | AmberDB | SQLite | Traditional RDBMS (PostgreSQL/MySQL) |
| :--- | :--- | :--- | :--- |
| **Architecture** | Embedded (In-process Perl object) | Embedded C Library | Standalone Client-Server Daemon |
| **External Dependencies** | Standard Perl (`DB_File`) | C Library / DBI Driver | Server Daemon, Networking, ORM |
| **Record Model** | Extensible Array Document | Relational Rows & Columns | Relational Rows & Columns |
| **Relational JOINs** | JOIN-Free Nested Records | SQL `JOIN` | SQL `JOIN` |
| **Indexing Structure** | 64-bit Packed Binary (`Q*`) | B-Tree | B-Tree / GiST / GIN |
| **Full-Text Search** | Built-in (Locale & Accent-Aware) | SQLite FTS5 Module | Full-Text Engine / External (Elasticsearch) |
| **Faceted Filtering** | Built-in Columnar Bitwise (`.fac`) | Manual Queries | Manual Queries / External Engine |
| **ACID Transactions** | Undo Journal + Strict 2PL | WAL / Rollback Journal | WAL / MVCC |

---

## 🔗 Resources & Community

* **GitHub Repository:** [https://github.com/marufcetin/amberdb](https://github.com/marufcetin/amberdb)
* **Comprehensive Wiki:** [https://github.com/marufcetin/amberdb/wiki](https://github.com/marufcetin/amberdb/wiki)
* **MetaCPAN Distribution:** [https://metacpan.org/pod/AmberDB](https://metacpan.org/pod/AmberDB)
* **Bug Tracker & Issues:** [https://github.com/marufcetin/amberdb/issues](https://github.com/marufcetin/amberdb/issues)
* **License:** [Artistic License 2.0](https://github.com/marufcetin/amberdb/blob/main/LICENSE)