AmberDB

🏠 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

This site is open source. Improve this page.