view release on metacpan or  search on metacpan

docs/EN.AmberDB_User-Guide.md  view on Meta::CPAN

### 13.1 What is RAM-Disk Acceleration?

Unlike network-based cache layers (such as Redis or Memcached), AmberDB's RAM-disk engine operates directly at the operating system filesystem block level. It maps tables and indexes directly to an operating-system-level in-memory mount point (Window...

**Key Architectural Differences:**
* **Zero External Daemons:** No Redis or Memcached server processes to install, configure, monitor, or manage.
* **Zero Network Latency:** Access occurs via direct local filesystem syscalls (`pread`, `pwrite`, `mmap`) rather than TCP sockets or IPC overhead.
* **Unified Data Format:** Stores the exact same native Berkeley DB (`.db`) and binary index files (`.inx`, `.fld`, etc.) as disk storage, eliminating serialization translation layers.
* **Process-Shared Memory:** Shared seamlessly across all concurrent Perl processes, Apache/FastCGI workers, and cron jobs.

### 13.2 How It Works

* **Native File Format Mirroring:** AmberDB stores all table files on RAM-disk using their exact native extensions (`.db`, `.inx`, `.fld`, `.src`, `.fac`, `.unq`, `.slg`). Proprietary `.cache` file formats are completely retired.
* **Synchronous Dual-Writing:** When a record is created or modified, the engine writes to both the persistent disk and the RAM-disk synchronously. Reads are served at RAM speeds; disk permanence is never compromised.
* **ACID Transaction Protection:** Writes to RAM-disk are fully protected by AmberDB's WAL undo-journaling (`dbstore/journal/txn_*`) and Strict 2PL locking. If a transaction rolls back, changes across both persistent disk and RAM-disk are cleanly res...
* **Automated Mount Verification & Strict Zero-Fallback:** Before accessing RAM-disk files, the engine verifies that the RAM-disk is actively mounted. When unmounted, all RAM-disk paths (`ramdisk_dir`, `table_rdir`, `schema_rdir`, `config_rdir`) eval...

### 13.3 RAM-Disk vs. L1 Process Cache

AmberDB distinguishes between two distinct caching and in-memory layers:

| Feature | Physical RAM-Disk Layer (`use_ramdisk`) | L1 In-Memory Process Cache (`get_cache` / `set_cache`) |
| :--- | :--- | :--- |
| **Scope** | Cross-process, system-wide shared memory | Single Perl process / worker memory |
| **Storage Engine** | Native `DB_File` and binary index files | Internal Perl hash references |
| **Persistence** | Synchronized with permanent disk (Tiers 1, 2 & 4) | Process lifetime only |
| **Methods** | `insert_id`, `read_id`, `search_table`, `modify_id` | `$adb->get_cache()`, `$adb->set_cache()` |

```perl
# L1 In-Memory Process Cache Operations
$adb->set_cache("dashboard", "active_users", @user_ids);
my @users = $adb->get_cache("dashboard", "active_users");
$adb->set_cache("dashboard", "active_users", undef); # Invalidate
```

### 13.4 Acceleration Tiers (`use_ramdisk`)

Tables are assigned an acceleration tier in their `.table` schema or dynamically via `table_attr()`:

* **`0` (Disabled):** Standard persistent disk access.
* **`1` (Hybrid Index-Only Acceleration):** Only secondary index files (`.inx`, `.src`, `.fld`, `.fac`, `.unq`, `.slg`) are placed in RAM-disk and synchronously dual-written to physical disk. Master data (`.db`) remains on physical disk. Searches, fi...
* **`2` (Full RAM-Disk Mirror - Dual-Write):** Both data (`.db`) and all index files are mirrored on RAM-disk. Reads are served directly from RAM-disk; writes dual-write synchronously to both layers.
* **`3` (Volatile Pure RAM-Disk - Simple Key-Value):** Data exists **strictly on RAM-disk** (`.db`). Zero physical disk files and zero index files are created (`use_simple => 1`). Designed for ephemeral sessions, shopping carts, and transient tokens....
* **`4` (Asynchronous Write-Behind):** Reads and writes execute at microsecond RAM speeds. Disk writes are deferred and dirty events are queued to `dbstore/journal/sync_ramdisk`. A background daemon (`amberdb_daemon.pl`) flushes changes to disk. Duri...

### 13.5 Transparent Management: `use_ramdisk` Configuration

No special read/write functions are needed to manage the RAM-disk layer; everything is handled automatically in the background. Management is performed entirely through the `use_ramdisk` configuration option:

#### 1. Global Configuration (Default for All Tables)
You can enable index or full-table acceleration across the entire database in one step:

```perl
# Apply Tier 1 (Hybrid Index) to all tables upon initialization
my $adb = AmberDB->new(
    cfg  => { use_ramdisk => 1 },
    path => { dbase_dir   => "/var/data/amberdb" }
);

# Dynamically change global tier at runtime
$adb->config(use_ramdisk => 2); # Switch all tables to Tier 2 (Full Mirror)
```

#### 2. Per-Table Flexible Configuration and Overrides
Each table can be independently assigned its own acceleration tier in its `.table` schema file or at runtime via `table_attr()`:

```perl
# Put high-traffic categories table into Full RAM-Disk Mirroring
$adb->table_attr("catalog_category", use_ramdisk => 2);

# Exclude an infrequently accessed archive table from RAM-disk (keep on disk)
$adb->table_attr("audit_archive", use_ramdisk => 0);
```

#### 3. Direct Usage via Standard CRUD Calls
Developers only use standard AmberDB methods. The underlying engine transparently handles RAM-disk preloading, memory-speed reads, and synchronous dual-writes:

```perl
# Reads: If use_ramdisk is defined, queries return directly from RAM in microseconds
my @product = $adb->read_id("catalog_product", 101);
my ($count, @results) = $adb->search_table("catalog_product", "wireless headphones");

# Writes: The engine automatically dual-writes to both persistent disk and RAM-disk
$adb->insert_id("catalog_product", 0, @new_product);
$adb->modify_id("catalog_product", 101, @updated_data);
```

### 13.6 RAM-Disk Administration & OS Integration

AmberDB natively supports platform-specific RAM-disk mounts:

- **Windows:** Mount via `bin\setup_windows.bat start 512M R:`, inspect status via `bin\setup_windows.bat status`, and unmount via `bin\setup_windows.bat stop R:`.
- **Linux:** `/dev/shm` is automatically utilized as the native shared-memory mount point.
- **macOS:** Mounted APFS RAM-disks under `/Volumes` are detected automatically.
- **Background Sync Daemon (Tier 4):** Started via `perl bin/amberdb_daemon.pl start`, inspected with `status`, and gracefully stopped with `stop`.
- **Storage Layout Synchronization:** Synchronize all required directories via `amberdb update storage` or `perl bin/amberdb_cli.pl update storage --force`.

### 13.7 Volatile Storage & Sliding TTL (`ramdisk_ttl`)

The `ramdisk_ttl` parameter strictly applies to **`use_ramdisk => 3` (volatile pure RAM-disk)** tables (default: 300 seconds). Expired sessions or carts are automatically purged on access:

```perl
# Configure session table as volatile RAM-disk with 30-minute sliding TTL
$adb->table_attr("session", {
    use_ramdisk => 3,
    ramdisk_ttl => 1800,      # 30-minute TTL (Tier 3 only)
    table_dir   => 'session'  # routes to ramdisk/session/
});
```

### 13.8 Custom Storage Subfolder (`table_dir`)

Tables default to `table/`. Use `table_dir` to specify custom folder organization:

```perl
# Route orders table to 'orders' subfolder:
# Physical: dbstore/orders/orders.db
# RAM-Disk: ramdisk/orders/orders.db
$adb->table_attr("orders", table_dir => 'orders');