/ 
AmberDB-5.23.1
/ docs/index.md

🏠 Home  •  📖 About  •  🚀 Quick Start  •  📘 Tutorial  •  🌐 Locale  •  📋 Changes  •  📚 Wiki  •  🇹🇷 Türkçe

CPAN version Perl Version License CI Documentation GitHub Repository

AmberDB is a high-performance, schema-driven, embedded NoSQL database engine for Perl. Built on Berkeley DB (DB_File), it provides $O(1)$ 64-bit packed binary indexing, ACID transactions with Strict Two-Phase Locking (Strict 2PL), JSON-like nested extensible array records without relational SQL JOIN bottlenecks, faceted category filtering, and a multi-tier hot/cold junk architecture.

📚 Documentation & Guides

| Section | Description | Link | | :--- | :--- | :--- | | About AmberDB | Architecture overview, design philosophy, why AmberDB, and core capabilities. | 📖 Read About AmberDB | | Tutorial & Developer Guide | Comprehensive manual covering CRUD operations, schemas, transactions, indexing, search, and best practices. | 📘 Open Developer Guide | | AmberDB::Locale Guide | Multilingual (9 languages) string processing, locale-aware case folding, accent/circumflex unfolding, and collation. | 🌐 Open Locale Guide | | Release Changes | Version history, recent architectural updates, and changelog. | 📋 View Changes | | Project Wiki | Method-by-method API documentation, concept deep-dives, flags, and file format references. | 📚 Open Project Wiki | | 🇹🇷 Türkçe Dokümantasyon | Türkçe ana sayfa, mimari makale, geliştirici kılavuzu ve dil kütüphanesi dokümanları. | 🇹🇷 Türkçe Sayfaya Geç |

🚀 Quick Start

1. Installation

Install AmberDB via CPAN or build from source:

# Via cpanm (Recommended)
cpanm AmberDB

# Or via standard CPAN shell
cpan AmberDB

Or install from GitHub source:

git clone https://github.com/marufcetin/amberdb.git
cd amberdb
perl Makefile.PL
make test
make install

2. Basic CRUD Example

Here is a complete, authentic CRUD walkthrough using AmberDB's array-based records:

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 JOINs, AmberDB stores records as natural, nested array tuples (including sub-arrays and sub-hashes). This matches Perl's native data structures and delivers ultra-fast retrieval.

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 rows.

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