/ 
AmberDB-5.22.1
/ AmberDB::Tools

NAME

AmberDB::Tools - Database maintenance, CLI reindexing, and bulk conversion toolset

SYNOPSIS

use AmberDB;
use AmberDB::Tools;

my $adb   = AmberDB->new(path => { dbase_dir => "/path/to/dbstore" });
my $tools = AmberDB::Tools->new($adb);

# 1. Create portable .amberdb database backup archive
my $archive = $tools->dump();

# 2. Restore database archive with integrity validation and reindexing
my $result  = $tools->restore(file => "backup.amberdb", force => 1);

# 3. Rebuild all indexes for a single table (.inx, .src, .fld, .fac, .srt)
$tools->set_index("catalog_product");

# 4. Rebuild only specific index components
$tools->set_search("catalog_product");  # Rebuild full-text search index
$tools->set_fields("catalog_product");  # Rebuild field exact match index
$tools->set_filters("catalog_product"); # Rebuild facet forward filter index
$tools->set_sort("catalog_product");    # Rebuild binary sort index

# 5. Batch reindex / convert all tables in database directory
my $report = $tools->convert_tables();

DESCRIPTION

AmberDB::Tools provides maintenance, native disaster recovery archiving (dump/restore), and batch utility functions for rebuilding indexes, populating full-text search inverted files, compiling forward facet filter dictionaries, generating binary sort matrices, and running automated database-wide index migrations.

CONSTRUCTOR

new($adb, [%options])

Creates an AmberDB::Tools instance associated with an active AmberDB object handle.

my $tools = AmberDB::Tools->new($adb);

METHODS

dump([%options])

Creates a compressed, portable .amberdb archive file (gzipped tar archive) containing table and database schemas (schema/*.table, schema/*.dbase), native database data files (tables/*.db, tables/*.del, tables/*.aut, tables/*.cnt), and a cryptographically verified SHA-256 manifest.json.

Options: =over 4 =item * file: Custom output file path (defaults to backup/YYYY/amberdb_YYYY-MM-DD_time.amberdb). =item * tables: Array reference of table IDs to include (defaults to all tables in database). =item * table: Single table ID to export as a focused snapshot. =back

my $archive = $tools->dump();
my $archive = $tools->dump(tables => ["catalog_product", "orders_cart"]);

restore(%options)

Restores a .amberdb archive into the target database. Validates archive integrity via SHA-256 checksums in manifest.json, extracts schemas and data files, and deterministically reconstructs all binary indexes (.inx, .src, .fld, .fac, .srt) via set_index.

Options: =over 4 =item * file: Path to .amberdb archive file (required). =item * force: Boolean (default 0). Must be set to 1 to overwrite existing tables in a non-empty database directory. =item * reindex: Boolean (default 1). Automatically executes set_index for all restored tables. =item * tables: Array reference of specific table IDs to extract from the archive. =back

my $res = $tools->restore(file => "backup.amberdb", force => 1);

set_index($table_id, [@records])

Rebuilds all secondary and primary indexes for $table_id based on its schema definition: =over 4 =item * Primary key index (.inx) via set_readall =item * Full-text search inverted indexes (_${blk}.src) via set_search =item * Inverted field match indexes (_${blk}.fld) via set_fields =item * Columnar facet filter forward indexes (_${blk}.fac) via set_filters =item * Monotonic binary pre-sorted record indexes (_${blk}.srt) via set_sort =back

If @records is omitted, reads all records from the base table automatically.

$tools->set_index("catalog_product");

set_readall($table_id, [@ids])

Rebuilds the primary .inx index file, populating keys (compact binary packed list of IDs), count, and lastid.

$tools->set_readall("catalog_product");

set_search($table_id, [@records])

Scans records, tokenizes text according to schema search_block, and builds inverted keyword index files (_${blk}.src).

$tools->set_search("catalog_product");

set_fields($table_id, [@records])

Builds inverted exact match index files (_${blk}.fld) for fields specified in schema match_block.

$tools->set_fields("catalog_product");

set_filters($table_id, [@records])

Builds columnar facet forward index files (_${blk}.fac) and bidirectional string dictionaries (_${blk}.unq) for blocks configured in schema facet_block.

$tools->set_filters("catalog_product");

set_sort($table_id, [@records])

Builds monotonic binary pre-sorted index files (_${blk}.srt) according to schema sort_block.

$tools->set_sort("catalog_product");

convert_tables()

Scans the entire database directory, identifies all physical tables, and sequentially runs set_index to rebuild and migrate packed binary indexes across the entire system. Returns a status hash reference.

my $status = $tools->convert_tables();

AUTHOR

Maruf Cetin <marufcetin@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2018-2026 Maruf Cetin.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.