Asterisk func_odbc dialplan lookups: DSN, escaping, rows and latency

Map every owner from dialplan to database

Treat the dialplan function, func_odbc.conf function class, res_odbc.conf connection name, operating-system ODBC DSN, driver, network path, database account, schema object and query as separate owners. The connection name referenced by func_odbc is an Asterisk res_odbc.conf section; its dsn in turn must match the system ODBC configuration. Preserve those names exactly rather than calling them all the database name.

A loaded res_odbc module, an entry shown by odbc show, a connected resource, a successful SQL statement, one matching row and a correct dialplan destination are different states. Record which state each check establishes before changing the next layer.

Prove modules, connection and configuration ownership

Asterisk documents res_odbc as the ODBC resource manager used by several subsystems and identifies func_odbc, res_odbc and res_odbc_transaction as relevant build modules. Confirm the installed package contains the required modules, that module policy does not block them, and that the owning distribution or managed PBX permits direct file changes.

Use odbc show to inventory the configured Asterisk connection and its current connection state, but do not treat the listing alone as proof that the intended query or schema works. Test the system DSN through its approved owner, then test one least-privilege Asterisk read function. Keep credentials out of console transcripts and tickets.

Define one function contract instead of arbitrary SQL

Each func_odbc.conf context defines a case-sensitive dialplan function with an explicit read handle and readsql. Give it a narrow purpose, fixed table and column set, documented argument count, expected row count, null policy and fallback. Use minargs so an omitted argument cannot accidentally reuse an unrelated channel ARGn value.

Do not expose the sample arbitrary-SQL pattern to callers or untrusted dialplan data. Give the database account only the permissions required for this function and keep write functions, insert fallbacks and transactions in separately reviewed contracts. A successful read is not authorization to perform a write.

Constrain and escape every substituted value

Validate each input against the business identifier it is meant to represent, then apply the escaping required by the selected database and Asterisk function. Asterisk documents SQL_ESC() for single quotes and SQL_ESC_BACKSLASHES() for backslashes when the database treats backslashes as escapes. Keep both the installed Asterisk maintenance level and the database escape mode in the acceptance record.

AST-2022-003 describes broken queries and a possible injection path when backslashes reach affected func_odbc versions, and records the maintenance releases that introduced the additional escaping function. Escaping is not a substitute for a constrained function, least-privilege account, supported maintenance release and query review.

Keep single-row and multirow results distinct

Default functions return the first result row. A mode=multirow function instead returns an opaque result identifier; ODBC_FETCH() retrieves each row and sets ODBC_FETCH_STATUS. The upstream sample also requires cleanup with ODBC_Finish and notes that multirow results remain associated with the channel that created them.

Set a bounded rowlimit and define what zero, one and multiple rows mean. Do not pass a result identifier to another channel or store it as durable application state. A non-empty result identifier is not a row value, and an exhausted result set is not necessarily a database failure.

Bound database latency on the live call path

Every synchronous lookup delays the dialplan branch that requested it. Set connection and query expectations with the database owner, preserve a deterministic timeout and fallback, and measure the complete lookup at normal and failure conditions. The res_odbc sample documents connection timeout, negative connection caching, optional query logging and a slow-query warning threshold; those controls answer different questions.

Accept connector state, query result and caller treatment separately. Rehearse unreachable database, slow response, zero rows, duplicate rows and invalid data with an authorized non-emergency flow. No driver, connection, query, result, channel, call delay or caller outcome was tested for this guide.

Review writes and transactions as a separate contract

After a bounded read is established, use the ODBC writes and transactions guide for authorization, VALn inputs, affected rows, explicit completion and concurrency.

Do not confuse func_odbc queries with PJSIP Realtime

The PJSIP Realtime guide covers Sorcery object retrieval and module configuration; func_odbc remains a separately named dialplan function contract.

Map ODBC fields to HASH or ARRAY deliberately

The HASH and ARRAY guide preserves the special single-argument HASH assignment boundary and validates ordered ARRAY input before routing.

Choose the lookup owner before choosing the function

The Asterisk CURL guide treats HTTP as a separate remote-service contract rather than an interchangeable replacement for database ownership and transactions.

Validate lookup output at the consumer boundary

The dialplan input guide prevents a present database value from becoming trusted routing data without shape and field checks.