mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
875 lines
29 KiB
875 lines
29 KiB
p_usrloc - Distributed databases
|
|
|
|
Henning Westerholt
|
|
|
|
1&1 Internet AG
|
|
|
|
Edited by
|
|
|
|
Patric Marschall
|
|
|
|
1&1 Internet AG
|
|
|
|
Copyright © 2007 1&1 Internet AG
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. User's Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. write_db_url (string)
|
|
3.2. read_db_url (string)
|
|
3.3. reg_db_table (string)
|
|
3.4. id_column (string)
|
|
3.5. num_column (string)
|
|
3.6. url_column (string)
|
|
3.7. status_column (string)
|
|
3.8. failover_time_column (string)
|
|
3.9. spare_flag_column (string)
|
|
3.10. error_column (string)
|
|
3.11. risk_group_column (string)
|
|
3.12. expire_time (int)
|
|
3.13. db_err_threshold (int)
|
|
3.14. failover_level (int)
|
|
3.15. db_retry_interval (int)
|
|
3.16. db_use_transactions (int)
|
|
3.17. db_transaction_level (string)
|
|
3.18. write_on_master_db (int)
|
|
3.19. write_on_db (int)
|
|
3.20. connection_expires (int)
|
|
3.21. alg_location (int)
|
|
3.22. domain_db(str)
|
|
3.23. default_db_type(str)
|
|
3.24. db_ops_ruid (int)
|
|
3.25. db_update_as_insert (string)
|
|
|
|
4. default_db_url(str)
|
|
5. Changes from usrloc module
|
|
|
|
5.1. db_mode (integer)
|
|
5.2. db_url
|
|
|
|
6. Installation & Running
|
|
|
|
6.1. Database setup
|
|
|
|
6.1.1. Configuration Table
|
|
|
|
6.2. Maintenance
|
|
6.3. Additional configuration
|
|
|
|
2. Developer's Guide
|
|
|
|
1. load_ul_db_api(ul_db_api_t * api)
|
|
2. int (* ul_db_insert_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
3. int (* ul_db_update_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_op_t * _op, db_val_t* _v, db_key_t* _uk,
|
|
db_val_t* _uv, int _n, int _un);
|
|
|
|
4. int (* ul_db_insert_update_t) (str * table, str * first, str *
|
|
second, db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
5. int (* ul_db_replace_t) (str * table, str * first, str *
|
|
second, db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
6. int (* ul_db_delete_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_op_t* _o, db_val_t* _v, int _n)
|
|
|
|
7. int (* ul_db_query_t) (str * table, str * first, str * second,
|
|
db_con_t *** _r_h, db_key_t* _k, db_op_t* _op, db_val_t*
|
|
_v, db_key_t* _c, int _n, int _nc, db_key_t _o, db_res_t**
|
|
_r);
|
|
|
|
8. int (* ul_db_free_result_t)(db_con_t ** dbh, db_res_t * res);
|
|
|
|
List of Examples
|
|
|
|
1.1. Set write_db_url parameter
|
|
1.2. Set read_db_url parameter
|
|
1.3. Set reg_db_table parameter
|
|
1.4. Set id_column parameter
|
|
1.5. Set num_column parameter
|
|
1.6. Set url_column parameter
|
|
1.7. Set status_column parameter
|
|
1.8. Set failover_time_column parameter
|
|
1.9. Set spare_flag_column parameter
|
|
1.10. Set error_column parameter
|
|
1.11. Set risk_group_column parameter
|
|
1.12. Set expire_time parameter
|
|
1.13. Set db_err_threshold parameter
|
|
1.14. Set failover_level parameter
|
|
1.15. Set db_retry_interval parameter
|
|
1.16. Set db_use_transactions parameter
|
|
1.17. Set db_transaction_level parameter
|
|
1.18. Set write_on_master_db parameter
|
|
1.19. Set write_on_db parameter
|
|
1.20. Set connection_expires parameter
|
|
1.21. Set alg_location parameter
|
|
1.22. Set domain_db parameter
|
|
1.23. Set default_db_type parameter
|
|
1.24. Set db_ops_ruid parameter
|
|
1.25. Set db_update_as_insert parameter
|
|
1.26. Set default_db_type parameter
|
|
1.27. Set db_mode parameter
|
|
1.28. Example database content - reg_table (locdb) table
|
|
|
|
Chapter 1. User's Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. write_db_url (string)
|
|
3.2. read_db_url (string)
|
|
3.3. reg_db_table (string)
|
|
3.4. id_column (string)
|
|
3.5. num_column (string)
|
|
3.6. url_column (string)
|
|
3.7. status_column (string)
|
|
3.8. failover_time_column (string)
|
|
3.9. spare_flag_column (string)
|
|
3.10. error_column (string)
|
|
3.11. risk_group_column (string)
|
|
3.12. expire_time (int)
|
|
3.13. db_err_threshold (int)
|
|
3.14. failover_level (int)
|
|
3.15. db_retry_interval (int)
|
|
3.16. db_use_transactions (int)
|
|
3.17. db_transaction_level (string)
|
|
3.18. write_on_master_db (int)
|
|
3.19. write_on_db (int)
|
|
3.20. connection_expires (int)
|
|
3.21. alg_location (int)
|
|
3.22. domain_db(str)
|
|
3.23. default_db_type(str)
|
|
3.24. db_ops_ruid (int)
|
|
3.25. db_update_as_insert (string)
|
|
|
|
4. default_db_url(str)
|
|
5. Changes from usrloc module
|
|
|
|
5.1. db_mode (integer)
|
|
5.2. db_url
|
|
|
|
6. Installation & Running
|
|
|
|
6.1. Database setup
|
|
|
|
6.1.1. Configuration Table
|
|
|
|
6.2. Maintenance
|
|
6.3. Additional configuration
|
|
|
|
1. Overview
|
|
|
|
The p_usrloc module is built upon the usrloc module and provides the
|
|
same usrloc export to the registrar module (for example). The usrloc
|
|
module must not be loaded at the same time with the p_usrloc module.
|
|
The parameters and the interface for the p_usrloc module are thus
|
|
almost the same, so in this document only extra parameters (specific
|
|
only to p_usrloc module) and differences are noted. For a complete
|
|
description of the paramters that are inherited from usrloc see the
|
|
page here. Note that the modparam statement must still refer to the
|
|
p_usrloc module.
|
|
|
|
The goal of the p_usrloc module is to provide partionioned user
|
|
location service to Kamailio/SER. This provides three major benefits:
|
|
* Redundancy Failure of a location database does not mean that the
|
|
location service is down
|
|
* Load Balancing DB performance is greatly increased as queries are
|
|
automatically split on a pool of ID(number configurable at
|
|
runtime). Furthermore, a read only db handler can be used to
|
|
further increase the spead of the "select" queries.
|
|
* Failover A faulty DB server is detected and taken out. When it
|
|
recovers, the module makes sure that no stale contacts are returned
|
|
from it.
|
|
|
|
Write queries are replicated to two or more databases, depending on
|
|
some distribution keys, e.g. the username and domain the subscribers.
|
|
The number of databases used for replication is configurable at compile
|
|
time by modifying the DB_NUM define. Its main field of application is
|
|
for storing and retrieving location data. The actual database for this
|
|
subscriber is choosen from a set that is specified in the master
|
|
database. Read queries are executed on one database of the set. If this
|
|
database is not available, the other database would be used. This
|
|
failure is recorded in the master database.
|
|
|
|
Connections to the distributed databases are setup prior the actual
|
|
query is executed. The module maintains a cache of the database handles
|
|
to provide better performance. This handles are periodically checked if
|
|
there are still valid and if needed updated from the master database.
|
|
As default only one key is used for the database lookup, but the
|
|
additional usage of a second one is possible.
|
|
|
|
Changes in the master database are autodetected. For better performance
|
|
it is possible to use one read-only instance, that is locally
|
|
installed, and write only errors and other status information to a
|
|
central master database. It is also possible to specify different
|
|
failover schemas and even use transaction to provide additional data
|
|
safety. This module could further try to minimise the impact of a
|
|
database error with the usage of spare databases that are automatically
|
|
activated. It also supports the manual deactivation of redundant
|
|
databases for maintenance purposes.
|
|
|
|
Warning
|
|
|
|
The p_usrloc module still has some missing feature, like automatic
|
|
expiry of contacts and dumping of all users via the fifo cmd.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* a database module necessary to connect to the master database and
|
|
to the distributed databases.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None.
|
|
|
|
3. Parameters
|
|
|
|
3.1. write_db_url (string)
|
|
3.2. read_db_url (string)
|
|
3.3. reg_db_table (string)
|
|
3.4. id_column (string)
|
|
3.5. num_column (string)
|
|
3.6. url_column (string)
|
|
3.7. status_column (string)
|
|
3.8. failover_time_column (string)
|
|
3.9. spare_flag_column (string)
|
|
3.10. error_column (string)
|
|
3.11. risk_group_column (string)
|
|
3.12. expire_time (int)
|
|
3.13. db_err_threshold (int)
|
|
3.14. failover_level (int)
|
|
3.15. db_retry_interval (int)
|
|
3.16. db_use_transactions (int)
|
|
3.17. db_transaction_level (string)
|
|
3.18. write_on_master_db (int)
|
|
3.19. write_on_db (int)
|
|
3.20. connection_expires (int)
|
|
3.21. alg_location (int)
|
|
3.22. domain_db(str)
|
|
3.23. default_db_type(str)
|
|
3.24. db_ops_ruid (int)
|
|
3.25. db_update_as_insert (string)
|
|
|
|
3.1. write_db_url (string)
|
|
|
|
The url to the master database where errors are written to.
|
|
|
|
Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”
|
|
|
|
Example 1.1. Set write_db_url parameter
|
|
...
|
|
modparam("p_usrloc", "write_db_url", "mysql://username:password@localhost/databa
|
|
sename")
|
|
...
|
|
|
|
3.2. read_db_url (string)
|
|
|
|
The url to the master database where the distribution data is read
|
|
from. It is seperated from write access, so for better performance, a
|
|
local replicate can be used for read access.
|
|
|
|
Default value is mysql://kamailio:kamailiorw@localhost/kamailio .
|
|
|
|
Example 1.2. Set read_db_url parameter
|
|
...
|
|
modparam("p_usrloc", "read_db_url", "mysql://user:passwd@localhost/db")
|
|
...
|
|
|
|
3.3. reg_db_table (string)
|
|
|
|
Specifies the table where the information about the distributed
|
|
databases is stored.
|
|
|
|
Default value is “locdb”.
|
|
|
|
Example 1.3. Set reg_db_table parameter
|
|
...
|
|
modparam("p_usrloc", "reg_db_table", "locdb")
|
|
...
|
|
|
|
3.4. id_column (string)
|
|
|
|
Specifies the column where the id of a distributed database is stored.
|
|
|
|
Default value is “id”.
|
|
|
|
Example 1.4. Set id_column parameter
|
|
...
|
|
modparam("p_usrloc", "id_column", "id")
|
|
...
|
|
|
|
3.5. num_column (string)
|
|
|
|
Specifies the column where the associated number of the distributed
|
|
database is stored. For each distributed database ID there must be at
|
|
least two databases available, the databases above the second are
|
|
ignored.
|
|
|
|
Default value is “no”.
|
|
|
|
Example 1.5. Set num_column parameter
|
|
...
|
|
modparam("p_usrloc", "num_column", "nr")
|
|
...
|
|
|
|
3.6. url_column (string)
|
|
|
|
Specifies the column where the url of the distributed database is
|
|
stored.
|
|
|
|
Default value is “url”.
|
|
|
|
Example 1.6. Set url_column parameter
|
|
...
|
|
modparam("p_usrloc", "url_column", "url")
|
|
...
|
|
|
|
3.7. status_column (string)
|
|
|
|
Specifies the column where the status of the distributed database is
|
|
stored.
|
|
|
|
Default value is “status”.
|
|
|
|
Example 1.7. Set status_column parameter
|
|
...
|
|
modparam("p_usrloc", "status_column", "status")
|
|
...
|
|
|
|
3.8. failover_time_column (string)
|
|
|
|
Specifies the column where the failover time of the location databases
|
|
is stored. This field is set to the current time when a databases is
|
|
turned off or turned on.
|
|
|
|
Default value is “failover”.
|
|
|
|
Example 1.8. Set failover_time_column parameter
|
|
...
|
|
modparam("p_usrloc", "failover_time_column", "fail")
|
|
...
|
|
|
|
3.9. spare_flag_column (string)
|
|
|
|
Specifies the column where the spare flag of the location databases is
|
|
stored. It is possible to declare an entry in the p_usrloc table as
|
|
spare which is used in a failover. Due to the fact that the data is
|
|
stored in two databases and it takes the spare the complete expire time
|
|
to be up to date, it is not very useful.
|
|
|
|
Default value is “spare”.
|
|
|
|
Example 1.9. Set spare_flag_column parameter
|
|
...
|
|
modparam("p_usrloc", "spare_flag_column", "spare")
|
|
...
|
|
|
|
3.10. error_column (string)
|
|
|
|
Specifies the column where the errors of the distributed databases are
|
|
stored. Each call to db_handle_error increases the error counter. After
|
|
exceeding the error threshold, the database's status is set to off.
|
|
|
|
Default value is “errors”.
|
|
|
|
Example 1.10. Set error_column parameter
|
|
...
|
|
modparam("p_usrloc", "error_column", "error")
|
|
...
|
|
|
|
3.11. risk_group_column (string)
|
|
|
|
Specifies the column where the risk group of the distributed databases
|
|
is stored. All databases on one host are in the same risk group. This
|
|
is only useful when using spares and prevents the module from taking a
|
|
spare which shares the same risk as the broken database.
|
|
|
|
Default value is “rg”.
|
|
|
|
Example 1.11. Set risk_group_column parameter
|
|
...
|
|
modparam("p_usrloc", "risk_group_column", "rg")
|
|
...
|
|
|
|
3.12. expire_time (int)
|
|
|
|
Specifies the time (in seconds) when a contact expires, used for
|
|
resetting the failover time of a reactivated database. It should be
|
|
equal or greater than the contact expiration time of the registrar
|
|
module.
|
|
|
|
Default value is “3600”.
|
|
|
|
Example 1.12. Set expire_time parameter
|
|
...
|
|
modparam("p_usrloc", "expire_time", "3600")
|
|
...
|
|
|
|
3.13. db_err_threshold (int)
|
|
|
|
Specifies the error value on which a database shall be turned of.
|
|
|
|
Default value is “50”.
|
|
|
|
Example 1.13. Set db_err_threshold parameter
|
|
...
|
|
modparam("p_usrloc", "db_err_threshold", "50")
|
|
...
|
|
|
|
3.14. failover_level (int)
|
|
|
|
Specifies the manner a failover is done. Following modes are supported:
|
|
* 1 - Just turn off the broken database
|
|
* 2 - Try to find a spare, if none found, just turn off the broken
|
|
database
|
|
|
|
Default value is “1”.
|
|
|
|
Example 1.14. Set failover_level parameter
|
|
...
|
|
modparam("p_usrloc", "failover_level", "1")
|
|
...
|
|
|
|
3.15. db_retry_interval (int)
|
|
|
|
Specifies the interval (in seconds) in which a timer process shall
|
|
check the availability of the databases and try to reconnect to broken
|
|
ones. It don't make sense to choose a lower value as 10. It's necessary
|
|
to provide a writeable master database, otherwise this check stays
|
|
disabled.
|
|
|
|
Default value is “10”.
|
|
|
|
Example 1.15. Set db_retry_interval parameter
|
|
...
|
|
modparam("p_usrloc", "db_retry_interval", "10")
|
|
...
|
|
|
|
3.16. db_use_transactions (int)
|
|
|
|
Specifies if transactions should be used (set to 1) to reach a higher
|
|
data consistency. Keep in mind that this will probably decrease
|
|
performance.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.16. Set db_use_transactions parameter
|
|
...
|
|
modparam("p_usrloc", "db_use_transactions", "0")
|
|
...
|
|
|
|
3.17. db_transaction_level (string)
|
|
|
|
Specifies the isolation level on which transactions are performed.
|
|
Possible values: Modes supported by the database backend. In order to
|
|
activate transaction the db_use_transactions parameter must be also
|
|
set.
|
|
|
|
Default value is “READ UNCOMMITED”.
|
|
|
|
Example 1.17. Set db_transaction_level parameter
|
|
...
|
|
modparam("p_usrloc", "db_transaction_level", "READ UNCOMMITED")
|
|
...
|
|
|
|
3.18. write_on_master_db (int)
|
|
|
|
Sets the write access to the master database. If set to 0, no write
|
|
operations are permitted on the master database.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.18. Set write_on_master_db parameter
|
|
...
|
|
modparam("p_usrloc", "write_on_master_db", "0")
|
|
...
|
|
|
|
3.19. write_on_db (int)
|
|
|
|
Sets the write access to the distributed databases. If set to 0, no
|
|
write operations are permitted on the databases.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.19. Set write_on_db parameter
|
|
...
|
|
modparam("p_usrloc", "write_on_db", "0")
|
|
...
|
|
|
|
3.20. connection_expires (int)
|
|
|
|
Specifies the period (in seconds) after a database connection expires.
|
|
Usage of a too small value will probably decrease the performance.
|
|
|
|
Default value is “300”.
|
|
|
|
Example 1.20. Set connection_expires parameter
|
|
...
|
|
modparam("p_usrloc", "connection_expires", "300")
|
|
...
|
|
|
|
3.21. alg_location (int)
|
|
|
|
Specify the way the distribution of the subscriptions are computed. At
|
|
the moment the only way is to use the CRC32 algorithm to compute the
|
|
location ID. Any integer value is fine.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.21. Set alg_location parameter
|
|
...
|
|
modparam("p_usrloc", "alg_location", 1)
|
|
...
|
|
|
|
3.22. domain_db(str)
|
|
|
|
Specify the way the lookup is made. In can be either partitioned or
|
|
single. For example, if you have a location table that is large and
|
|
needs to be partitioned, and a smaller table cfa that is ok to be on
|
|
only the master db(so there is no need to have it distributed), you can
|
|
set this parameter to “location=cluster,cfa=single”. This means that a
|
|
call to
|
|
lookup(location)
|
|
|
|
will be done via the partition databases configured via the
|
|
reg_db_table parameter, but a call to
|
|
lookup(cfa)
|
|
|
|
will be done on only the master database (as with usrloc module)
|
|
|
|
Default value is “location=cluster,cfa=single”.
|
|
|
|
Example 1.22. Set domain_db parameter
|
|
...
|
|
modparam("p_usrloc", "domain_db", "location=cluster,cfa=single")
|
|
...
|
|
|
|
3.23. default_db_type(str)
|
|
|
|
In case a domain (like location,cfa) is not matched by a domain_db
|
|
definition, the type is configured by using this parameter. Accepted
|
|
values are single and cluster.
|
|
|
|
Default value is “single”.
|
|
|
|
Example 1.23. Set default_db_type parameter
|
|
...
|
|
modparam("p_usrloc", "default_db_type", "cluster")
|
|
...
|
|
|
|
3.24. db_ops_ruid (int)
|
|
|
|
If set to 1, database queries for update or delete are done using ruid
|
|
value. If it is set to 0, the old style using aor, contact and call-id
|
|
is done.
|
|
|
|
Default value is “1”.
|
|
|
|
Example 1.24. Set db_ops_ruid parameter
|
|
...
|
|
modparam("p_usrloc", "db_ops_ruid", 0)
|
|
...
|
|
|
|
3.25. db_update_as_insert (string)
|
|
|
|
Set this parameter if you want to do INSERT DB operations instead of
|
|
UPDATE DB operations. It is recommended to set this parameter if you
|
|
use Cassandra as a DB backend.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.25. Set db_update_as_insert parameter
|
|
...
|
|
modparam("usrloc", "db_update_as_insert", 1)
|
|
...
|
|
|
|
4. default_db_url(str)
|
|
|
|
The URL of the default database for Location domains (for domains that
|
|
are single). This must be configured if they are use.
|
|
|
|
Default value is “DEFAULT_DB_URL”.
|
|
|
|
Example 1.26. Set default_db_type parameter
|
|
...
|
|
modparam("p_usrloc", "default_db_url", "mysql://ser:ser@localhost/ser")
|
|
...
|
|
|
|
5. Changes from usrloc module
|
|
|
|
5.1. db_mode (integer)
|
|
5.2. db_url
|
|
|
|
5.1. db_mode (integer)
|
|
|
|
The p_usrloc module must utilize database for persistent contact
|
|
storage. Only mode 3 is possible at this time. Because of the way other
|
|
matching mode work, they make no sense on a distributed environment.
|
|
* 3 - DB-Only scheme. No memory cache is kept, all operations being
|
|
directly performed with the database. The timer deletes all expired
|
|
contacts from database - cleans after clients that didn't
|
|
un-register or re-register. The mode is useful if you configure
|
|
more servers sharing the same DB without any replication at SIP
|
|
level. The mode may be slower due the high number of DB operation.
|
|
For example NAT pinging is a killer since during each ping cycle
|
|
all nated contact are loaded from the DB; The lack of memory
|
|
caching also disable the statistics exports.
|
|
|
|
Default value is 3.
|
|
|
|
Example 1.27. Set db_mode parameter
|
|
...
|
|
modparam("p_usrloc", "db_mode", 2)
|
|
...
|
|
|
|
5.2. db_url
|
|
|
|
This parameters is now obsolete, and replaced by specific p_usrloc
|
|
parameters
|
|
|
|
6. Installation & Running
|
|
|
|
6.1. Database setup
|
|
|
|
6.1.1. Configuration Table
|
|
|
|
6.2. Maintenance
|
|
6.3. Additional configuration
|
|
|
|
6.1. Database setup
|
|
|
|
6.1.1. Configuration Table
|
|
|
|
Before running Kamailio with p_usrloc, you have to setup the master
|
|
database table where the module will find data about the distributed
|
|
databases. For that, if the table was not created by the installation
|
|
script or you choose to install everything by yourself you can use the
|
|
p_usrloc-create.sql SQL script in the database directories in the
|
|
openser/scripts folder as template. Database and table name can be set
|
|
with module parameters so they can be changed, but the name of the
|
|
columns must be as they are in the SQL script. You can also find the
|
|
complete database documentation on the project webpage,
|
|
http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
|
|
|
|
Example 1.28. Example database content - reg_table (locdb) table
|
|
...
|
|
+----+----+------+--------+--------+---------------------+-------+----+
|
|
| id | no | url | status | errors | failover | spare | rg |
|
|
+----+----+------+--------+--------+---------------------+-------+----+
|
|
| 1 | 1 | URL1 | 1 | 0 | 1900-01-01 00:00:01 | 0 | 0 |
|
|
| 1 | 2 | URL2 | 1 | 0 | 1900-01-01 00:00:01 | 0 | 0 |
|
|
| 2 | 1 | URL3 | 1 | 0 | 1900-01-01 00:00:01 | 0 | 0 |
|
|
| 2 | 2 | URL4 | 1 | 0 | 1900-01-01 00:00:01 | 0 | 0 |
|
|
+----+----+------+--------+--------+---------------------+-------+----+
|
|
...
|
|
|
|
The URLs are omitted for a better overview, but you can use standard
|
|
Kamailio database URLs like
|
|
mysql://kamailio:kamailiorw@localhost/kamailio Databases don't need to
|
|
be on different hosts, e.g. for testing purposes.
|
|
|
|
This table contains two database groups. The first with id one, and the
|
|
second with the id two.
|
|
|
|
6.2. Maintenance
|
|
|
|
The module supports the decativation of redundant databases for
|
|
maintenance reasons. This can be done by setting the status column of
|
|
the respective database in the p_usrloc to the value “2”. This setting
|
|
is autodetected from all modules on the server cluster. Changes in the
|
|
locdb table are periodically polled with help of a timer process. After
|
|
one minute the all read and write traffic is removed from the
|
|
deactivated database, and maintenance can be done.
|
|
|
|
In order to activate the database again, after the maintenance has been
|
|
finished, the respective status column needs to be set to “0”. This is
|
|
autodetected as well, the first module that noticed the change will set
|
|
the status column to “1” and setting the failover column to the current
|
|
time and date. Write requests are now transfered again to the database,
|
|
but no reads are done yet.
|
|
|
|
After the configured expire_time has been passed, i.e. every contact
|
|
has been inserted at least one time in the database the respective
|
|
failover time column is set to the default value again. The database is
|
|
then also used to read contacts from, the cluster is in normal
|
|
operation with full redundancy again.
|
|
|
|
6.3. Additional configuration
|
|
|
|
As this module is only used internally from other modules, there is no
|
|
additional configuration except for the module parameter setup
|
|
necessary.
|
|
|
|
Chapter 2. Developer's Guide
|
|
|
|
Table of Contents
|
|
|
|
1. load_ul_db_api(ul_db_api_t * api)
|
|
2. int (* ul_db_insert_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
3. int (* ul_db_update_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_op_t * _op, db_val_t* _v, db_key_t* _uk,
|
|
db_val_t* _uv, int _n, int _un);
|
|
|
|
4. int (* ul_db_insert_update_t) (str * table, str * first, str *
|
|
second, db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
5. int (* ul_db_replace_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
6. int (* ul_db_delete_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_op_t* _o, db_val_t* _v, int _n)
|
|
|
|
7. int (* ul_db_query_t) (str * table, str * first, str * second,
|
|
db_con_t *** _r_h, db_key_t* _k, db_op_t* _op, db_val_t* _v,
|
|
db_key_t* _c, int _n, int _nc, db_key_t _o, db_res_t** _r);
|
|
|
|
8. int (* ul_db_free_result_t)(db_con_t ** dbh, db_res_t * res);
|
|
|
|
These are the primary functions that are used to perform the SQL
|
|
queries.
|
|
|
|
1. load_ul_db_api(ul_db_api_t * api)
|
|
|
|
Import the dbd API, setup the master database connection.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* api - Pointer to distributed database API structure
|
|
|
|
2. int (* ul_db_insert_t) (str * table, str * first, str * second, db_key_t*
|
|
_k, db_val_t* _v, int _n)
|
|
|
|
Lookup the first and if needed the second key, and insert the given
|
|
values into the choosen databases.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* table - Pointer to the table name.
|
|
* first - Pointer to the first key.
|
|
* second - Pointer to the second key.
|
|
* _k - Pointer to the inserted db keys.
|
|
* _v - Pointer to the inserted db values.
|
|
* _n - Number of key-value pairs in _k and _v parameters.
|
|
|
|
3. int (* ul_db_update_t) (str * table, str * first, str * second, db_key_t*
|
|
_k, db_op_t * _op, db_val_t* _v, db_key_t* _uk, db_val_t* _uv, int _n, int
|
|
_un);
|
|
|
|
Lookup the first and if needed the second key, and update the given
|
|
values in the choosen databases.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* table - Pointer to the table name.
|
|
* first - Pointer to the first key.
|
|
* second - Pointer to the second key.
|
|
* _k - Pointer to the db keys that will be matched.
|
|
* _op - Pointer to the db options for this operation.
|
|
* _v - Pointer to the db values that will be matched.
|
|
* _uk - Pointer to the updated db keys.
|
|
* _uv - Pointer to the updated db values.
|
|
* _n - Number of key-value pairs in _k and _v parameters.
|
|
* _un - Number of key-value pairs in _uk and _uv parameters.
|
|
|
|
4. int (* ul_db_insert_update_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
Lookup the first and if needed the second key, and insert on duplicate
|
|
key update the given values in the choosen databases. This is like an
|
|
insert, but update if the key already exist.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* table - Pointer to the table name.
|
|
* first - Pointer to the first key.
|
|
* second - Pointer to the second key.
|
|
* _k - Pointer to the inserted or updated db keys.
|
|
* _v - Pointer to the inserted or updated db values.
|
|
* _n - Number of key-value pairs in _k and _v parameters.
|
|
|
|
5. int (* ul_db_replace_t) (str * table, str * first, str * second,
|
|
db_key_t* _k, db_val_t* _v, int _n)
|
|
|
|
Lookup the first and if needed the second key, and replace the given
|
|
values in the choosen databases.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* table - Pointer to the table name.
|
|
* first - Pointer to the first key.
|
|
* second - Pointer to the second key.
|
|
* _k - Pointer to the replaced db keys.
|
|
* _v - Pointer to the replaced db values.
|
|
* _n - Number of key-value pairs in _k and _v parameters.
|
|
|
|
6. int (* ul_db_delete_t) (str * table, str * first, str * second, db_key_t*
|
|
_k, db_op_t* _o, db_val_t* _v, int _n)
|
|
|
|
Lookup the first and if needed the second key, and delete the given
|
|
values into the choosen databases.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* table - Pointer to the table name.
|
|
* first - Pointer to the first key.
|
|
* second - Pointer to the second key.
|
|
* _k - Pointer to the deleted db keys.
|
|
* _op - Pointer to the db options for this operation.
|
|
* _v - Pointer to the deleted db values.
|
|
* _n - Number of key-value pairs in _k and _v parameters.
|
|
|
|
7. int (* ul_db_query_t) (str * table, str * first, str * second, db_con_t
|
|
*** _r_h, db_key_t* _k, db_op_t* _op, db_val_t* _v, db_key_t* _c, int _n, int
|
|
_nc, db_key_t _o, db_res_t** _r);
|
|
|
|
Lookup the first and if needed the second key, and performs a query in
|
|
one of the choosen databases. The returned handle _r_h must be used to
|
|
free the result set after the usage of the returned database entries,
|
|
otherwise a memory leak will occur.You must call ul_db_free_result
|
|
before you can call ul_db_query again!
|
|
|
|
Meaning of the parameters is as follows:
|
|
* table - Pointer to the table name.
|
|
* first - Pointer to the first key.
|
|
* second - Pointer to the second key.
|
|
* _r_h - Pointer to the result handle, to free the result.
|
|
* _op - Pointer to the db options for this operation.
|
|
* _k - Pointer to the queried db keys.
|
|
* _v - Pointer to the queried db values.
|
|
* _c - Pointer to the db keys that should be returned.
|
|
* _n - Number of key-value pairs in _k and _v parameters.
|
|
* _nc - Number of key-value pairs in _c parameter.
|
|
* _o - Order by options for the query.
|
|
* _nc - Pointer to the result set.
|
|
|
|
8. int (* ul_db_free_result_t)(db_con_t ** dbh, db_res_t * res);
|
|
|
|
Frees the given result set, .
|
|
|
|
Meaning of the parameters is as follows:
|
|
* dbh - Pointer to the result handle.
|
|
* res - Pointer to the result.
|