/ 
AmberDB-5.26.0
/ AmberDB::Tools

NAME

AmberDB::Tools - Database maintenance, CLI reindexing, migrations, 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)
$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 pre-sorted sequences in .inx

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

# 6. Database storage & engine migrations
$tools->update_storage(force => 0);     # Migrate scheme/->schema/, tables/->table/, TSV->ABR v5
$tools->update_version(check => 1);     # Check MetaCPAN for latest release

DESCRIPTION

AmberDB::Tools provides maintenance, native disaster recovery archiving (dump/restore), 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 and storage migrations.

Functionality is organized into focused sub-modules:

  • AmberDB::Tools::Index: Index generation routines (set_index, set_readall, set_search, set_fields, set_filters, set_rwlnkall, set_sort, index_alltables, check_readall, check_search).

  • AmberDB::Tools::Maintain: Maintenance, export/import, and backup routines (dump, restore, vacuum, del_table, tie2csv, csv2tie, dir_tables, all_tables).

  • AmberDB::Tools::Update: Table format conversions, storage upgrades, and engine updating (update_table, update_all, replace_tablename, replace_blockdata, db_simple, convert_tables, update_storage, update_version).

All operations can also be invoked directly from the terminal via amberdb CLI (e.g. amberdb update storage, amberdb update version, amberdb reindex products).

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 (table/*.db, table/*.del, table/*.aut, table/*.cnt), and a cryptographically verified SHA-256 manifest.json.

Options:

  • file: Custom output file path (defaults to backup/YYYY/amberdb_YYYY-MM-DD_time.amberdb).

  • tables: Array reference of table IDs to include (defaults to all tables in database).

  • table: Single table ID to export as a focused snapshot.

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) via set_index.

Options:

  • file: Path to .amberdb archive file (required).

  • force: Boolean (default 0). Must be set to 1 to overwrite existing tables in a non-empty database directory.

  • reindex: Boolean (default 1). Automatically executes set_index for all restored tables.

  • tables: Array reference of specific table IDs to extract from the archive.

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:

  • Primary key index (.inx) via set_readall

  • Full-text search inverted indexes (.src) via set_search

  • Inverted field match indexes (.fld) via set_fields

  • Columnar facet filter forward indexes (.fac) via set_filters

  • Monotonic binary pre-sorted record indexes (within .inx) via set_sort

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 file (.src).

$tools->set_search("catalog_product");

set_fields($table_id, [@records])

Builds inverted exact match index file (.fld) for fields specified in schema match_block.

$tools->set_fields("catalog_product");

set_filters($table_id, [@records])

Builds columnar facet forward index files (.fac) and bidirectional string dictionary (.unq) for blocks configured in schema facet_block.

$tools->set_filters("catalog_product");

set_sort($table_id, [@records])

Builds monotonic binary pre-sorted index sequences within .inx ($blk:keys) 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();

update_table($table_id, [%options])

Scans an entire table record-by-record, detects legacy formats, creates a timestamped backup, and rewrites the table in native ABR v5 format while rebuilding indexes.

my $res = $tools->update_table("catalog_product", force => 1);

update_storage([%options])

Migrates storage directories (scheme/ to schema/, tables/ to table/), converts legacy TSV tables to native ABR v5 format, rebuilds all indexes, and stamps config/storage_version.json.

Options: check, force, no_backup, tables, target_dir.

$tools->update_storage(force => 1);

update_version([%options])

Queries the MetaCPAN API for newer releases of AmberDB, and optionally invokes cpanm to upgrade the engine.

Options: check, cpanm.

$tools->update_version(check => 1);

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.