/ 
AmberDB-5.25.1
/ amberdb_cli.pl

NAME

amberdb_cli.pl - High-performance Command-Line Console & Embedded Management Utility for AmberDB

SYNOPSIS

# 1. Overview Dashboard (lists all tables, records, size, engine status)
perl bin/amberdb_cli.pl
perl bin/amberdb_cli.pl format=json

# 2. Token-Based Session Lifecycle (Connect, Configure & Disconnect)
perl bin/amberdb_cli.pl connect path-dbase_dir=./dbstore cfg-language=tr
perl bin/amberdb_cli.pl token=K2A78T02 cfg-no_write=1
perl bin/amberdb_cli.pl token=K2A78T02 disconnect

# 3. Dynamic In-Memory Schema Customization (table_attr)
perl bin/amberdb_cli.pl token=K2A78T02 action=table_attr table=products keep_deleted=1 search_block=[2,3,6]

# 4. CRUD & Query Operations
perl bin/amberdb_cli.pl token=K2A78T02 action=read_id table=users id=10
perl bin/amberdb_cli.pl token=K2A78T02 action=read_all table=products offset=0 limit=20 dir=asc
perl bin/amberdb_cli.pl token=K2A78T02 action=read_list table=users ids=1,2,5,10
perl bin/amberdb_cli.pl token=K2A78T02 action=search_table table=products query="laptop" limit=10
perl bin/amberdb_cli.pl token=K2A78T02 action=insert_id table=users id=0 data='{"name":"Ahmet","status":1}'
perl bin/amberdb_cli.pl token=K2A78T02 action=update_id table=users id=10 data='{"status":2}'
perl bin/amberdb_cli.pl token=K2A78T02 action=delete_id table=users id=10

# 5. Maintenance, Indexing & Disaster Recovery
perl bin/amberdb_cli.pl token=K2A78T02 action=reindex table=products
perl bin/amberdb_cli.pl token=K2A78T02 action=check table=products
perl bin/amberdb_cli.pl token=K2A78T02 action=vacuum table=products
perl bin/amberdb_cli.pl token=K2A78T02 action=export table=products file=products.csv
perl bin/amberdb_cli.pl token=K2A78T02 action=import table=products file=products.csv
perl bin/amberdb_cli.pl token=K2A78T02 action=drop table=temp_products force=1

DESCRIPTION

amberdb_cli.pl is a direct file-based command-line console and administrative utility for AmberDB. It bypasses network daemon overhead, operating directly upon native database files (.db, .inx, .fld, .src, .fac) at microsecond embedded speeds.

Key capabilities include:

  • Interactive & Non-Interactive Dashboard: Running with no arguments renders an overview of all database tables, record counts, file sizes, and storage directories.

  • Token-Based Session Persistence: State, paths, language codes, safety flags, and runtime schema mutations (table_attr) persist across terminal invocations via short session tokens (stored under .amberdb_sessions/).

  • Full CRUD Suite: Supports positional or key-value record reading, pagination (offset/limit), full-text phonetic search, and bulk operations.

  • Maintenance & Utilities: Native disaster recovery archiving (dump/restore), CSV export/import, binary index rebuilding (reindex), database compacting (vacuum), and schema inspection.

  • Dynamic Method Reflection: Any method supported by AmberDB or AmberDB::Tools can be dispatched dynamically via action=<method>.

SESSIONS & ARGUMENT CONVENTIONS

Argument Formats

Arguments can be passed flexibly using standard shell key-value syntax:

  • Key-value pairs: table=products, id=10, action=read_id

  • Option dashes: --table=products, -table=products, table:products

  • Nested path/config values: path-dbase_dir=./dbstore, cfg-language=tr, cfg-no_write=1

Session Lifecycle

  • connect: Generates a new 8-character token and saves database configuration. Automatically persists to cli_last_token so subsequent commands can omit token=....

  • token=TOKEN: Reuses an existing session state and its registered table attributes.

  • disconnect: Closes and purges the active session file.

ACTIONS

Inspection & Dashboard

  • overview / list: Displays table summary table (name, record count, byte size, index status).

  • table_info: Inspects table schema definitions, metadata, and block configurations.

  • table_attr: Dynamically updates or queries in-memory schema attributes (e.g. search_block, keep_deleted, RDBM relationships).

CRUD & Queries

  • read_id: Reads a single record by primary key ID in $O(1)$ time.

  • read_all: Scans and streams active records with support for pagination, sorting (dir=asc|desc), and range filtering.

  • read_list: Bulk fetches records by a comma-separated list of IDs (ids=1,2,5).

  • search_table: Full-text search matching query keywords with phonetic and accent normalization.

  • insert_id: Inserts a new record. Supports JSON format (data='{...}') or positional fields. Pass id=0 for auto-increment.

  • update_id: Modifies an existing record by ID.

  • delete_id: Deletes a record by ID (honors keep_deleted audit archive if enabled).

Maintenance & Administration

  • reindex: Rebuilds all derived binary indexes (.inx, .fld, .src, .fac, .unq, .slg) via AmberDB::Tools.

  • check: Validates physical table integrity and reports corruption or key anomalies.

  • vacuum: Reorganizes and compacts Berkeley DB storage files, reclaiming free space.

  • export / import: High-speed CSV data export and import.

  • dump / restore: Full portable compressed database archive management (.amberdb).

  • drop: Deletes a physical table and all secondary indexes. Requires force=1 for safety.

OUTPUT FORMATS

The output format can be controlled using format=<type>:

  • table: (Default) Human-readable ASCII terminal table.

  • json: Machine-readable JSON output, ideal for shell pipelines, Web UIs, and external scripts.

  • raw: Direct Perl Data::Dumper serialization.

SEE ALSO

AmberDB, AmberDB::Tools, amberdb_setup.pl

Official Wiki: https://github.com/marufcetin/amberdb/wiki/Guide-CLI

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.