DB_HTTP module
Admin Guide
Section titled “Admin Guide”Overview
Section titled “Overview”This module provides access to a database that is implemented as a HTTP server. It may be used in special cases where traversing firewalls is a problem, or where data encryption is required.
In order to use this module you must have a server that can communicate via HTTP or HTTPS with this module that follows exactly the format decribed in the specifications section.
The module can provide SSL, authentication, and all the functionalities of an opensips db as long as the server supports them ( except result_fetch).
There is a slight difference between the url of db_http and the urls of the other db modules. The url doesn’t have to contain the database name. Instead, everything that is after the address is considered to be a path to the db resource, it may be missing.
Even if using HTTPS the url must begin with “http://” , and the SSL parameter for the module must be set to 1.
...modparam("presence", "db_url","http://user:pass@localhost:13100")ormodparam("presence", "db_url","http://user:pass@www.some.com/some/some")...Dependencies
Section titled “Dependencies”OpenSIPS Modules
Section titled “OpenSIPS Modules”This module does not depend on other modules.
External Libraries or Applications
Section titled “External Libraries or Applications”- libcurl.
Exported Parameters
Section titled “Exported Parameters”SSL(int)
Section titled “SSL(int)”Whether or not to use SSL.
If value is 1 the module will use https otherwise it will use http.
Default value is ” 0 “.
...modparam("db_http", "SSL",1)...cap_raw_query(int)
Section titled “cap_raw_query(int)”Whether or not the server supports raw queries.
Default value is “0”.
...modparam("db_http", "cap_raw_query", 1)...cap_replace(int)
Section titled “cap_replace(int)”Whether or not the server supports replace capabilities.
Default value is “0”.
...modparam("db_http", "cap_replace", 1)...cap_insert_update(int)
Section titled “cap_insert_update(int)”Whether or not the server supports insert_update capabilities.
Default value is “0”.
...modparam("db_http", "cap_insert_update", 1)...cap_last_inserted_id(int)
Section titled “cap_last_inserted_id(int)”Whether or not the server supports last_inserted_id capabilities.
Default value is “0”.
...modparam("db_http", "cap_last_inserted_id", 1)...field_delimiter (str)
Section titled “field_delimiter (str)”Character to be used to delimit fields in the reply.Only one char may be set.
Default value is ”;“
...modparam("db_http", "field_delimiter",";")...row_delimiter (str)
Section titled “row_delimiter (str)”Character to be used to delimit rows in the reply.Only one char may be set.
Default value is “\n”
...modparam("db_http", "row_delimiter","\n")...quote_delimiter (str)
Section titled “quote_delimiter (str)”Character to be used to quote fields that require quoting in the reply.Only one char may be set.
Default value is ”|“
...modparam("db_http", "quote_delimiter","|")...value_delimiter (str)
Section titled “value_delimiter (str)”The delimiter used to separate multiple fields of a single variable (see http variables). Only one char may be set.
Default value is ”,“
...modparam("db_http", "value_delimiter",";")...timeout (int)
Section titled “timeout (int)”The maximum number of milliseconds that the HTTP ops are allowed to last
Default value is “30000 ( 30 seconds )“
...modparam("db_http", "timeout",5000)...disable_expect (int)
Section titled “disable_expect (int)”Disables automatic ‘Expect: 100-continue’ behavior in libcurl for requests over 1024 bytes in size. This can help reduce latency by saving a network round-trip for large records. For more information on this behavior please seee rfc2616 section 8.2.3.
Default value is “0 (off)“
...modparam("db_http", "disable_expect",1)...Exported Functions
Section titled “Exported Functions”Server specifications
Section titled “Server specifications”Queries
Section titled “Queries”The server must accept queries as HTTP queries.
The queries are of 2 types : GET and POST.Both set variables that must be interpreted by the server. All values are URL-encoded.
There are several types of queries and the server can tell them apart by the query_type variable. Each type of query uses specific variables simillar to those in the opensips db_api.
...GET /presentity/?c=username,domain,event,expires HTTP/1.1...Variables
Section titled “Variables”A description of all the variables. Each variable can have either a single value or a comma-separated list of values. Each variable has a special meaning and can be used only with certain queries.
The table on which operations will take place will be encoded in the url as the end of the url ( www.some.com/users will point to the users table).
- k= Describes the keys (columns) that will be used for comparison.Can have multiple values.
- op= Describes the operators that will be used for comparison.Can have multiple values.
- v= Describes the values that columns will be compaired against. Can have multiple values.
- c= Describes the columns that will be selected from the result.Can have multiple values.
- o= The column that the result will be ordered by. Has a single value.
- uk= The keys(columns) that will be updated. Can have multiple values.
- uv= The new values that will be put in the columns. Can have multiple values.
- q= Describes a raw query. Will only be used if the server supports raw queries. Has a single value.
- query_type= Describes the type of the current query. Can have a single value as described in the Query Types section.Has a single value. Will be present in all queries except the “SELECT” (normal query).
...GET /presentity/?c=username,domain,event,expires HTTP/1.1GET /version/?k=table_name&v=xcap&c=table_version HTTP/1.1......POST /active_watchers HTTP/1.1
k=id&v=100&query_type=insert...Query Types
Section titled “Query Types”The types of the queries are described by the query_type variable. The value of the variable will be set to the exact name of the query.
Queries for “SELECT” use GET and the rest use POST (insert, update, delete, replace, insert_update).
- normal query Uses the k, op, v, c and o variables. This will not set the query_type variable and will use GET.
- delete Uses the k, op and v variables.
- insert Uses the k and v variables.
- update Uses the k,op,v,uk and uv variables.
- replace Uses the k and v variables. This is an optional type of query. If the module is not configured to use it it will not.
- insert_update Uses the k and v variables. This is an optional type of query. If the module is not configured to use it it will not.
- custom Uses the q variable. This is an optional type of query. If the module is not configured to use it it will not.
...POST /active_watchers HTTP/1.1
k=id&op=%3D&v=100&query_type=delete...
...POST /active_watchers HTTP/1.1
k=id&op=%3D&v=100&uk=id&uv=101&query_type=update...NULL values in queries
Section titled “NULL values in queries”NULL values in queries are represented as a string of length 1 containing a single character with value ‘\0’.
...POST /active_watchers HTTP/1.1
k=id&op=%3D&v=%00&query_type=delete...Server Replies
Section titled “Server Replies”If the query is ok (even if the answer is empty) the server must reply with a 200 OK HTTP reply with a body containing the types and values of the columns.
The server must reply with a delimiter separated list of values and columns.
Each element in the list must be seperated from the one before it by a field delimiter that must be the same as the one set as a parameter from the script for the module. The last element of each line must not be followed by a field delimiter, but by a row delimiter.
The first line of the reply must contain a list of the types of values of each column. The types can be any from the list: integer, string, str, blob, date.
Each following line contains the values of each row from the result.
If the query produced an error the server must reply with a HTTP 500 reply, or with a corresponding error code (404, 401).
...int;string;blob6;something=something;1000100;mine;10002030...Reply Quoting
Section titled “Reply Quoting”Because the values may contain delimiters inside, the server must perform quoting when necessary (there is no problem if it does it even when it is not necessary).
A quote delimiter must be defined and must be the same as the one set from the script ( by default it is ”|” ).
If a value contains a field , row or a quote delimiter it must be placed under quotes. A quote delimiter inside a value must be preceeded by another quote delimiter.
...int;string;blob6;|ana;maria|;1000100;mine;100020303;mine;|some||more;|...Last inserted id
Section titled “Last inserted id”This is an optional feature and may be enabled if one wants to use it.
In order to use this feature the server must place the id of the last insert in the 200 reply for each insert query.
Authentication and SSL
Section titled “Authentication and SSL”If the server supports authentication and SSL, the module can be enabled to use SSL. Authentication will always be used if needed.
The module will try to use the most secure type of authentication that is provided by the server from: Basic, Digest, GSSNEGOTIATE and NTLM.
Contributors
Section titled “Contributors”By Commit Statistics
Section titled “By Commit Statistics”Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| # | Name | DevScore | Commits | Lines++ | Lines— |
|---|---|---|---|---|---|
| 1. | Andrei Dragus | 23 | 2 | 2289 | 5 |
| 2. | Razvan Crainea (@razvancrainea) | 14 | 12 | 71 | 20 |
| 3. | Stefan Darius (@dariusstefan) | 11 | 4 | 588 | 88 |
| 4. | Liviu Chircu (@liviuchircu) | 10 | 7 | 69 | 91 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | 8 | 6 | 47 | 51 |
| 6. | Vlad Paiu (@vladpaiu) | 6 | 4 | 65 | 7 |
| 7. | Vlad Patrascu (@rvlad-patrascu) | 5 | 3 | 58 | 5 |
| 8. | Ryan Bullock (@rrb3942) | 5 | 3 | 44 | 3 |
| 9. | Dusan Klinec (@ph4r05) | 3 | 1 | 50 | 26 |
| 10. | Ovidiu Sas (@ovidiusas) | 3 | 1 | 11 | 5 |
All remaining contributors: Peter Lemenkov (@lemenkov), Ezequiel Lovelle (@lovelle), Stephane Alnet, Anca Vamanu.
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits
(3) ignoring whitespace edits, renamed files and auto-generated files
By Commit Activity
Section titled “By Commit Activity”| # | Name | Commit Activity |
|---|---|---|
| 1. | Stefan Darius (@dariusstefan) | Jun 2026 - Jul 2026 |
| 2. | Razvan Crainea (@razvancrainea) | Oct 2011 - Jun 2026 |
| 3. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Feb 2021 |
| 4. | Ovidiu Sas (@ovidiusas) | Mar 2020 - Mar 2020 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | Dec 2009 - Apr 2019 |
| 6. | Ryan Bullock (@rrb3942) | Jan 2019 - Feb 2019 |
| 7. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 8. | Liviu Chircu (@liviuchircu) | Mar 2014 - Jun 2018 |
| 9. | Dusan Klinec (@ph4r05) | Dec 2015 - Dec 2015 |
| 10. | Ezequiel Lovelle (@lovelle) | Oct 2014 - Oct 2014 |
All remaining contributors: Stephane Alnet, Vlad Paiu (@vladpaiu), Anca Vamanu, Andrei Dragus.
(1) including any documentation-related commits, excluding merge commits
Documentation
Section titled “Documentation”Contributors
Section titled “Contributors”Last edited by: Razvan Crainea (@razvancrainea), Ryan Bullock (@rrb3942), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Stephane Alnet, Vlad Paiu (@vladpaiu), Bogdan-Andrei Iancu (@bogdan-iancu), Andrei Dragus.
License
Section titled “License”All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0