Having fun yet? It gets even better!
Asterisk provides a powerful mechanism for storing values called the Asterisk database (AstDB). The AstDB provides a simple way to store data for use within your dialplan.
For those of you with experience using relational databases such as PostgreSQL or MySQL, the Asterisk database is not a traditional relational database. It is a Berkeley DB Version 1 database. There are several ways to store data from Asterisk in a relational database. Check out Chapter 12, Relational Database Integration for a more about relational databases.
The Asterisk database stores its data in groupings called families, with values
identified by keys. Within a family, a key may be
used only once. For example, if we had a family called test
, we could store only one value with a key
called count
. Each stored value must be
associated with a family.
To store a new value in the Asterisk database, we use the
Set()
application,[85] but instead of using it to set a channel variable, we use
it to set an AstDB variable. For example, to assign the count
key in the test
family with the value of 1
, write the following:
exten => 456,1,Set(DB(test/count)=1)
If a key named count
already
exists in the test
family, its value
will be overwritten with the new value. You can also store values from
the Asterisk command line, by running the command database put
family key
value
. For our example, you would type database
put test count 1
.
To retrieve a value from the Asterisk database and assign it to a
variable, we use the Set()
application again. Let’s retrieve the value of count
(again, from the test
family), assign it to a variable called
COUNT
, and then speak the value to
the caller:
exten => 456,1,Set(DB(test/count)=1)
exten => 456,n,Set(COUNT=${DB(test/count)})
exten => 456,n,SayNumber(${COUNT})
You may also check the value of a given key from the Asterisk
command line by running the command database get
family key
. To view the entire contents of
the AstDB, use the database show
command.
There are two ways to delete data from the Asterisk database. To
delete a key, you can use the DB_DELETE()
application. It takes the path to
the key as its arguments, like this:
; deletes the key and returns its value in one step exten => 457,1,Verbose(0, The value was ${DB_DELETE(test/count)})
You can also delete an entire key family by using the DBdeltree()
application. The DBdeltree()
application takes a single
argument―the name of the key family―to delete. To delete the entire
test
family, do the following:
exten => 457,1,DBdeltree(test)
To delete keys and key families from the AstDB via the
command-line interface, use the database del
key
and database deltree
family
commands, respectively.
There are an infinite number of ways to use the Asterisk database
in a dialplan. To introduce the AstDB, we’ll show two simple examples.
The first is a simple counting example to show that the Asterisk
database is persistent (meaning that it survives system reboots). In the
second example, we’ll use the BLACKLIST()
function to evaluate whether or
not a number is on the blacklist and should be blocked.
To begin the counting example, let’s first retrieve a number (the
value of the count
key) from the
database and assign it to a variable named COUNT
. If the key doesn’t exist, DB()
will return NULL (no value). In order to
verify if a value exists in the database or not, we will introduce the
ISNULL()
function that will verify
whether a value was returned, and if not, we will initialize the AstDB
with the Set()
application, where we
will set the value in the database to 1
. The next priority will send us back to
priority 1. This will happen the very first time we dial this
extension:
exten => 678,1,Set(COUNT=${DB(test/count)}) exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue) exten => 678,n,Set(DB(test/count)=1) exten => 678,n,Goto(1) exten => 678,n(continue),NoOp()
Next, we’ll say the current value of COUNT
, and then increment COUNT
:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1])
Now that we’ve incremented COUNT
, let’s put the new value back into the
database. Remember that storing a value for an existing key overwrites
the previous value:
exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1])
exten => 678,n,Set(DB(test/count)=${COUNT})
Finally, we’ll loop back to the first priority. This way, the application will continue counting:
exten => 678,1,Set(COUNT=${DB(test/count)}) exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue) exten => 678,n,Set(DB(test/count)=1) exten => 678,n,Goto(1) exten => 678,n(continue),NoOp() exten => 678,n,SayNumber(${COUNT}) exten => 678,n,Set(COUNT=$[${COUNT} + 1] exten => 678,n,Set(DB(test/count)=${COUNT}) exten => 678,n,Goto(1)
Go ahead and try this example. Listen to it count for a while, and then hang up. When you dial this extension again, it should continue counting from where it left off. The value stored in the database will be persistent, even across a restart of Asterisk.
In the next example, we’ll create dialplan logic around the
BLACKLIST()
function, which checks to
see if the current Caller ID number exists in the blacklist. (The
blacklist is simply a family called blacklist
in the AstDB.) If BLACKLIST()
finds the number in the blacklist,
it returns the value 1
, otherwise it will return
0
. We can use these values in combination with a
GotoIf()
to control whether the call
will execute the Dial()
application:
exten => 124,1,GotoIf($[${BLACKLIST()]?blocked,1) exten => 124,n,Dial(${JOHN}) exten => blocked,1,Playback(privacy-you-are-blacklisted) exten => blocked,n,Playback(vm-goodbye) exten => blocked,n,Hangup()
To add a number to the blacklist, run the database put
blacklist
number
1
command from the Asterisk command-line interface.
[85] Previous versions of Asterisk had applications
called DBput()
and
DBget()
that were used to set
values in and retrieve values from the AstDB. If you’re using an old
version of Asterisk, you’ll want to use those applications
instead.