VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk AMI AstDB: get, put, delete and tree evidence

Read, change or remove the intended AstDB key without confusing an accepted manager response, a broad tree operation or a local persistent value with application outcome evidence.

Reviewed 2026-10-19Current branch-23 AMI DBGet, DBGetTree, DBPut, DBDel and DBDelTree references, Asterisk internal-database and SQLite3 back-end guidance, and the AMI v2 specification were reviewed October 19, 2026. Installed branch, action availability, manager permissions, AstDB ownership, family and key conventions, value semantics, concurrent writers, configured storage location, backup consistency, restore procedure and downstream behavior remain deployment specific. No PBX, manager account, session, AstDB family, key, value, backend file, backup, restore, dialplan, packet, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Define the exact family, key and owner

AstDB is Asterisk's local persistent key-value store. Treat Family and Key together as the namespace: a familiar suffix, display label or value is not adequate identity. Record the node, deployed Asterisk branch, owning module or application, expected value format, permitted writers, consumers and retention rule before an AMI action.

Do not use AstDB as an assumed distributed database. A value that survives a reload or restart on one node is not evidence of cross-node replication, conflict resolution or successful recovery from a restored backup.

Choose a point read or bounded tree inventory

DBGet reads one Family and Key. DBGetTree can enumerate entries at an optional family and key boundary, but the current generated reference lists its introduction only on later supported branches. Inventory the actions visible to the authenticated manager user and provide a bounded fallback for older deployments rather than assuming every version supports DBGetTree.

Use a point read for a known key and a tree read only when discovery or subtree evidence is required. Limit and redact inventories because families can contain credentials, personal data or unrelated application state.

Correlate DBPut, then perform a fresh readback

DBPut requires Family, Key and Val. Assign a unique ActionID, preserve the matching response, then issue a fresh point read of the same family and key. AMI is asynchronous, so correlation is part of the evidence even when actions appear sequential in one client.

An accepted write and correct readback prove only the observed store boundary. They do not prove that this client was the only writer, that a dialplan or module consumed the value, that a backup contains it, or that another node received it.

Separate exact-key deletion from subtree deletion

DBDel targets one family and key. DBDelTree removes a tree at the supplied family and key boundary and therefore has a much larger blast radius. Before a tree delete, capture a bounded pre-change inventory, approval, exact namespace, consistent backup or other tested rollback asset, and an explicit list of values expected to remain.

After either operation, read the target again and inspect adjacent control keys. Never use a broader family because the intended key is hard to find, and do not treat an accepted deletion response as evidence that every dependent workflow recovered.

Coordinate writers, persistence and recovery

AstDB persistence does not serialize a business workflow across multiple AMI clients, dialplan code and modules. Identify every writer and protect read-modify-write sequences with an application-level ownership or locking design. A later correct value can hide an earlier overwrite, stale read or race.

Back up the configured AstDB storage using a method consistent with the deployed packaging and database back end. Do not edit or copy a live SQLite file as an ad hoc data-change method. Test restore procedures on an isolated system and verify family, key, value and consumer behavior separately.

Constrain the manager path and prove the consumer

AMI messages use key: value fields, CRLF line endings and a terminating empty line. Authenticate the intended manager identity, verify its live action inventory and grant only the necessary read or write classes plus network ACL and encrypted transport where supported. AMI class authorization is coarse-grained and is not, by itself, a complete security boundary.

Retain ActionID, response, exact namespace, readback and a separately observed dialplan or module outcome. Redact secrets and sensitive values. No PBX, manager account, session, AstDB family, key, value, backend file, backup, restore, dialplan, packet, media stream or live call was inspected or tested.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Troubleshooting · Current branch-23 AMI DBGet, DBGetTree, DBPut, DBDel and DBDelTree references, Asterisk internal-database and SQLite3 back-end guidance, and the AMI v2 specification were reviewed October 19, 2026. Installed branch, action availability, manager permissions, AstDB ownership, family and key conventions, value semantics, concurrent writers, configured storage location, backup consistency, restore procedure and downstream behavior remain deployment specific. No PBX, manager account, session, AstDB family, key, value, backend file, backup, restore, dialplan, packet, media stream or live call was inspected or tested

Asterisk AMI AstDB value is missing, stale or a tree delete is too broad

Trace AMI framing, action availability, exact family and key, writers, readback, deletion scope, local persistence and recovery before changing the dialplan.

Read guide →
Guide · Asterisk current internal-database overview and Latest API branch 23 DB, DB_EXISTS, DB_DELETE and DB_KEYS documentation reviewed October 14, 2026; installed version, loaded func_db module, database families, keys, values, file ownership, backup scope, concurrent writers, managed-PBX ownership and cross-node behavior remain deployment specific; no PBX, module, database file, key, value, dialplan, channel, backup, restore or call was inspected or tested

Asterisk AstDB: persistent local keys without confusing blank and absent

Use AstDB families and keys with explicit ownership, existence checks, bounded deletion and backup evidence while keeping local persistence separate from concurrency and cluster-wide state.

Read guide →
Guide · Asterisk branch-23-generated and branch-22-generated ListCommands references plus official AMI syntax, v2 specification, manager-command, change/versioning, permission, module-loader and network-security documentation reviewed October 16, 2026; installed branch and maintenance release, build, package and module set, manager user, read and write authorizations, session mask, action registration, request framing, parameters, target objects, response, related events and service outcome remain deployment specific; no PBX, module, package, manager user, manager session, request, response, event, configuration file, channel, packet, media stream or live call was inspected or tested

Asterisk AMI command inventory and permission evidence

Use ListCommands and the administrator CLI to distinguish the actions visible to one manager user from the actions registered by the running Asterisk instance.

Read guide →
Guide · Asterisk Latest API branch 23 LOCK, TRYLOCK and UNLOCK documentation, Asterisk 22 SHARED documentation and current global-variable guidance reviewed October 14, 2026; function availability, loaded func_lock and func_global modules, exact lock names, channel ownership, protected data, wait duration, dialplan branches and external side effects remain deployment specific; no PBX, module, dialplan, channel, lock, variable, database row, file, external service or call was inspected or tested

Asterisk dialplan locks: serialize shared state without hiding call failure

Use LOCK, TRYLOCK and UNLOCK around the smallest shared-state update, preserve channel ownership and failure branches, and keep the protected operation distinct from mutex acquisition.

Read guide →
Guide · Asterisk 22 LTS operational documentation reviewed October 5, 2026; no PBX, archive, database, module, credential, voicemail, recording, route, call, recovery point or recovery time tested

Backing up and restoring standalone Asterisk

Recover the running Asterisk service by inventorying configured paths, mutable state, external databases, secrets and the exact software build.

Read guide →
Guide · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →