view release on metacpan or  search on metacpan

docs/EN.About_AmberDB.md  view on Meta::CPAN

[🏠 Home](index.html)  â€¢  [📖 About](EN.About_AmberDB.html)  â€¢  [🚀 Quick Start](index.html#-quick-start)  â€¢  [📘 Tutorial](EN.AmberDB_User-Guide.html)  â€¢  [🌐 Locale](EN.AmberDB-Locale_User-G...

---

# About

**AmberDB** is an embedded NoSQL database engine for Perl that processes Array-based records supporting JSON-like nested and complex structures. Thanks to custom indexes generated through schema definitions, it performs block matching, querying, full...

It is built on the C code of Berkeley DB (`DB_File`) provided by the standard Perl package and does not use any other database engine. `DB_File` is Berkeley DB's low-level interface that provides key-value access via Perl. AmberDB constructs a data m...

---

## Why AmberDB?

AmberDB brings together diverse capabilities within a single Perl database engine:

* **No External Database Server:** Embedded directly into the application as an in-process object.
* **Array-Based Records:** Database records are Arrays (lists) supporting JSON-like nested structures.
* **Full CRUD Operations:** Fast, direct insert, read, update, and delete methods.
* **Flexible Indexing:** Operates seamlessly both with and without indexes. Requires no separate setup for indexing.
* **Full-Text Search:** High-performance search (both indexed and unindexed).
* **Sorting & Versatile Queries:** Multi-field sorting, range queries, and regex filtering.
* **Nested & Repeating Blocks:** Automatic management of relational and repeating data blocks.
* **Multi-Table Relational Transactions:** ACID-compliant transaction management with Strict 2-Phase Locking (Strict 2PL).
* **Faceted Filtering:** Dynamic faceted filtering generation, just like on modern e-commerce sites.
* **RAM-to-Disk Tiering:** RAM buffer caching layer similar to Redis.
* **High-Throughput Batch Processing:** Dedicated bulk ingestion and index-merge pipeline.
* **Audit Logging:** Built-in logging of user operations on each record.
* **Soft Deletes:** Table-definition-specific soft delete (stores deleted records in an archive tier).
* **Automatic SEO Slugs:** Automatic URL slug generation for catalog tables.
* **Portable Backups:** Portable `.amberdb` database archives and restore tools with SHA-256 verification.

> **Core Principle:**  
> The database should make common application data operations simple, fast, and predictable.

---

## Quick Introductory Example

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

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

# 2. Define product record
my @product = (
    0,                       # id (0 for auto-increment)
    "Wireless Headphones",   # name
    149.99,                  # price
    "Sony",                  # brand
    "Electronics",              # category
    { status => "In Stock" }    # status hash ref
);

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

# 4. Reading the record back:
my @product_fromdb = $adb->read_id("products", $id);

docs/EN.About_AmberDB.md  view on Meta::CPAN

This is especially advantageous when the application's natural domain model looks like this:

```
Order
├── Order ID
├── Customer ID
├── Address
├── Dates [as an array: order date, shipping date, delivery date]
├── Payment
├── Status
└── Products (repeating rows, each row being an array)
    ├── Product ID
    ├── Product Name
    ├── Quantity
    ├── Price
    └── Discount
```

Instead of distributing information across multiple tables and reconstructing it via joins at read time as in SQL, the application retains it directly as a single variable (array), matching Perl's native data model much more closely.

---

## Transactions and ACID Compliance

Despite being a performance-oriented NoSQL engine, AmberDB provides multi-table ACID transactions using an undo log and Strict Two-Phase Locking (Strict 2PL). AmberDB also supports concurrent access via OS-level file locking, making it suitable for m...

```perl
$adb->transact_start();

# 1. Update order status
# 2. Update customer account
# 3. Update inventory
# 4. Insert payment record

$adb->transact_end();
```

If an error occurs, the entire transaction—including associated index changes—is rolled back. The undo log also ensures recovery following an unexpected process or system failure.

---

## Batch Operations for Large Imports

AmberDB utilizes batch operations for bulk data ingestion and processing. It provides dedicated methods for loading bulk records via imports such as XML, ETL, and CSV, updating existing records (e.g., updating a price list), or performing bulk deleti...

AmberDB provides the following batch methods:

```perl
$adb->insert_list("products", @records); # batch insert
$adb->modify_list("products", @records); # batch modify
$adb->delete_list("products", @ids);     # batch delete
```

For instance, when inserting a list of one thousand records using `insert_list`, AmberDB creates the records and their indexes in a single batch process. Similarly, a massive price list can be modified within a single batch operation. This makes batc...

---

## Portable Backups

Because AmberDB is file-based, it is fully portable. It also includes safer native database tools for backup and restoration.

A database can be exported into a portable `.amberdb` archive containing the authoritative database state and schema. Integrity is verified using SHA-256, and derived indexes are rebuilt during restoration. This makes it possible to migrate or archiv...

---

## Epilogue

AmberDB provides an experience close to **PostgreSQL + Elasticsearch + Redis**, achieving this at an extremely low footprint and cost. It requires no standalone server installation and embeds directly into your application. It consumes minimal system...

AmberDB is released under the **Artistic License 2.0**. Source code, documentation, and examples are available and actively maintained on CPAN and GitHub.

* **GitHub Issues:** [https://github.com/marufcetin/amberdb/issues](https://github.com/marufcetin/amberdb/issues)
* **MetaCPAN:** [https://metacpan.org/pod/AmberDB](https://metacpan.org/pod/AmberDB)

If you are interested in database systems or are a Perl developer, explore AmberDB and give it a try!