Asterisk AstDB: persistent local keys without confusing blank and absent

Choose AstDB only for local persistent state

Asterisk documents its internal database as storage used by modules and exposed to administrators and dialplan authors. Values persist across reloads and restarts. Since Asterisk 10 the documented backend is SQLite3, but that implementation detail does not turn AstDB into an application database, a replicated store or a cluster transaction service.

Name the owning feature, family, key format, value contract, retention, backup and restore path before writing. Keep transient per-channel values in channel variables, and use an external store when several nodes or systems require one authoritative transaction boundary.

Keep family, key and value as separate evidence

DB(family/key) reads or writes one value. On a read it returns the value or blank when the key does not exist, and also sets DB_RESULT. A blank result therefore cannot by itself distinguish an absent key from a present key whose value is blank. Use DB_EXISTS(family/key) when that distinction affects routing.

Normalize only bounded identifiers that the application owns. A different case, slash, prefix, tenant component or number format names different data. Do not construct administrative keys directly from untrusted caller input, and do not display secret-bearing values in logs or shared tickets.

Use existence and value checks deliberately

DB_EXISTS() returns 1 or 0 and sets DB_RESULT to the key value when the entry exists. Preserve the existence result before another function changes channel variables, then validate the returned value against the expected schema before acting on it.

A present key is not proof that its value is current, authorized, complete or owned by the dialplan reading it. Record the producer, last approved update and fallback branch separately. Treat a default value as an explicit policy decision rather than silently converting missing data into success.

Treat deletion as a state change

DB_DELETE() retrieves the prior value and removes the key; it is not a lookup-only operation. The function sets DB_RESULT when the key existed. Confirm the exact family and key, the authorized owner, expected previous value and recovery path before executing it.

Bulk CLI deletion and DBdeltree can affect an entire family or subtree. Preview with bounded database get, database showkey, database show or DB_KEYS() evidence, retain a backup where appropriate, and avoid deleting module-owned or managed-PBX state merely because a row looks stale.

Do not mistake enumeration for a transaction

DB_KEYS(prefix) returns a comma-separated list of keys under the selected prefix, or family names when no prefix is supplied. The result is an inventory aid, not proof that every value was read consistently or remained unchanged while later dialplan steps ran.

For a multi-step read-modify-write invariant, use the dialplan-lock guide and protect the complete local sequence with one normalized lock contract. The reviewed AstDB pages do not establish cross-node locking, compare-and-swap, replication, remote durability or an atomic batch spanning several keys.

Verify persistence, recovery and caller outcome separately

For an authorized non-production family, record the installed Asterisk version, function availability, exact key, existence result, value, write result, CLI readback, reload or restart boundary, backup inclusion, restore result and final dialplan destination. Include an absent-key control, a present blank value and a deliberately rejected value.

Use Asterisk interfaces rather than editing the live SQLite file directly. Keep live_dangerously=no unless a reviewed integration requires otherwise; DB_DELETE() documents a restriction on direct external-protocol execution under that setting. This guide is documentation-derived. No PBX, database, key, restore or call was tested.

Keep lookup evaluation separate from persistent state

If evaluated data reads AstDB, use the dialplan lookup guide to distinguish exact target existence, target-context evaluation and any later database update.

Choose local key-value state and transactional SQL deliberately

The ODBC transaction guide covers authorized relational writes, named transactions, isolation and rollback rather than treating every persistent value as AstDB state.

Persistent state can be polled without becoming synchronized state

The WaitForCondition diagnostic keeps AstDB presence, value freshness, writer timing, locking and condition truth separate.

Keep HASH separate from persistent AstDB state

The HASH and ARRAY guide treats structured dialplan state and a persistent AstDB family as different owners with different lifecycle evidence.

Add an explicit AMI contract to AstDB state

The AMI AstDB guide maps DBGet, DBGetTree, DBPut, DBDel and DBDelTree to exact evidence and recovery boundaries.