sql_cacher_admin.xml

<!-- SQL Cacher Module User's Guide -->

<chapter>
    
    <title>&adminguide;</title>

    <section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
	The sql_cacher module introduces the possibility to cache data from a
	SQL-based database (using different &osips; modules which implement the DB API)
	into a cache system implemented in &osips; through the CacheDB Interface.
	This is done by specifying the databases URLs, SQL table to be used, desired
	columns to be cached and other details in the &osips; configuration script.
	</para>
	<para>
	The cached data is available in the script through the read-only pseudovariable
	<quote>$sql_cached_value</quote> similar to a Key-Value system. A specified
	column from the SQL table has the role of <quote>key</quote> therefore the value
	of this column along with the name of a required column are provided as
	"parameters" to the pseudovariable returning the appropriate value of the column.
	</para>
	<para>
	There are two types of caching available:
	<itemizedlist>
		<listitem><para>
		<emphasis>full caching</emphasis> - the entire SQL table (all the rows) is loaded
		into the cache at &osips; startup;
		</para></listitem>
		<listitem><para>
		<emphasis>on demand</emphasis> - the rows of the SQL table are loaded at runtime
		when appropriate keys are requested.
		</para></listitem>
	</itemizedlist>
	</para>
	<para>
	For on demand caching, the stored values have a configurable expire period after
	which they are permanently removed unless an MI reload function is called for a
	specific key. In the case of full caching the data is automatically reloaded at
	a configurable interval. Consequently if the data in the SQL database changes
	and a MI reload function is  called, the old data remains in cache only
	until it expires.
	</para>
	</section>
	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<para>
	    The following modules must be loaded before this module:
	    <itemizedlist>
		<listitem>
		    <para><emphasis>The &osips; modules that offer actual database back-end
		    	connection</emphasis></para>
		</listitem>
	    </itemizedlist>
	</para>
    </section>
    <section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_cache_table" xreflabel="cache_table">
		<title><varname>cache_table</varname> (string)</title>
		<para>
		This parameter can be set multiple times in order to cache multiple SQL
		tables or even the same table but with a different configuration. The module
		distinguishes those different entries by an <quote>id</quote> string.
		</para>
		<para>
		The caching entry is specified via this parameter that has it's own
		subparameters. Each of those parameters are separated by a
		delimiter configured by <xref linkend="param_spec_delimiter"/>
		and have the following format:
		<para><emphasis>param_name=param_value</emphasis></para>
		The parameters are:
		<itemizedlist>
			<listitem><para>
			<emphasis>id</emphasis> : cache entry id
			</para></listitem>
			<listitem><para>
			<emphasis>db_url</emphasis> : the URL of the SQL database
			</para></listitem>
			<listitem><para>
			<emphasis>cachedb_url</emphasis> : the URL of the CacheDB database
			</para></listitem>
			<listitem><para>
			<emphasis>table</emphasis> : SQL database table name
			</para></listitem>
			<listitem><para>
			<emphasis>key</emphasis> : SQL database column name of the <quote>key</quote> column
			</para></listitem>
			<listitem><para>
			<emphasis>key_type</emphasis> : data type for the SQL "key" column:
			<itemizedlist>
				<listitem><para>
					string
				</para></listitem>
				<listitem><para>
					int
				</para></listitem>
			</itemizedlist>
			<para>If not present, default value is <quote>string</quote></para>
			</para></listitem>
			<listitem><para>
			<emphasis>columns</emphasis> : names of the columns to be cached from the
			SQL database, separated by a delimiter configured by
			<xref linkend="param_columns_delimiter"/>.
			<para>If not present, all the columns from the table will be cached</para>
			</para></listitem>
			<listitem><para>
			<emphasis>on_demand</emphasis> : specifies the type of caching:
			<itemizedlist>
				<listitem><para>
					0 : full caching
				</para></listitem>
				<listitem><para>
					1 : on demand
				</para></listitem>
			</itemizedlist>
			<para>If not present, default value is <quote>0</quote></para>
			</para></listitem>
			<listitem><para>
			<emphasis>expire</emphasis> : expire period for the values stored
			in the cache for the on demand caching type in seconds
			<para>If not present, default value is <quote>1 hour</quote></para>
			</para></listitem>
		</itemizedlist>
		</para>
		<para>
		The parameters must be given in the exact order specified above.
		</para>
		<para>
		Overall, the parameter does not have a default value, it must be set
		at least once in order to cache any table.
		</para>
		<example>
		<title><varname>cache_table</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "cache_table",
"id=caching_name
db_url=mysql://root:opensips@localhost/opensips_2_2
cachedb_url=mongodb:mycluster://127.0.0.1:27017/db.col
table=table_name
key=column_name_0
columns=column_name_1 column_name_2 column_name_3
on_demand=0")
   
</programlisting>
	    </example>
	</section>

	<section id="param_spec_delimiter" xreflabel="spec_delimiter">
		<title><varname>spec_delimiter</varname> (string)</title>
		<para>
		The delimiter to be used in the caching entry specification provided in the
		<emphasis>cache_table</emphasis> parameter to separate the subparameters. It
		must be a single character.
		</para>
		<para>
		The default value is newline.
		</para>
		<example>
		<title><varname>spec_delimiter</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "spec_delimiter", "\n")
   
</programlisting>
	    </example>
	</section>

	<section id="param_pvar_delimiter" xreflabel="pvar_delimiter">
		<title><varname>pvar_delimiter</varname> (string)</title>
		<para>
		The delimiter to be used in the <quote>$sql_cached_value</quote>
		pseudovariable to separate the caching id, the desired column name
		and the value of the key. It must be a single character.
		</para>
		<para>
		The default value is <quote>:</quote>.
		</para>
		<example>
		<title><varname>pvar_delimiter</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "pvar_delimiter", " ")
   
</programlisting>
	    </example>
	</section>

	<section id="param_columns_delimiter" xreflabel="columns_delimiter">
		<title><varname>columns_delimiter</varname> (string)</title>
		<para>
		The delimiter to be used in the <emphasis>columns</emphasis> subparameter of
		the caching entry specification provided in the <emphasis>cache_table</emphasis>
		parameter to separate the desired columns names. It must be a single character.
		</para>
		<para>
		The default value is <quote> </quote>(space).
		</para>
		<example>
		<title><varname>columns_delimiter</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "columns_delimiter", ",")
   
</programlisting>
	    </example>
	</section>

	<section id="param_sql_fetch_nr_rows" xreflabel="sql_fetch_nr_rows">
		<title><varname>sql_fetch_nr_rows</varname> (integer)</title>
		<para>
		The number of rows to be fetched into &osips; private memory in one chunk from
		the SQL database driver. When querying large tables, adjust this parameter
		accordingly to avoid the filling of &osips; private memory. 
		</para>
		<para>
		The default value is <quote>100</quote>.
		</para>
		<example>
		<title><varname>sql_fetch_nr_rows</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "sql_fetch_nr_rows", 1000)
   
</programlisting>
	    </example>
	</section>

	<section id="param_full_caching_expire" xreflabel="full_caching_expire">
		<title><varname>full_caching_expire</varname> (integer)</title>
		<para>
		Expire period for the values stored in cache for the full caching type
		in seconds. This is the longest time that deleted or modified data remains
		in cache.
		</para>
		<para>
		The default value is <quote>24 hours</quote>.
		</para>
		<example>
		<title><varname>full_caching_expire</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "full_caching_expire", 3600)
   
</programlisting>
	    </example>
	</section>

	<section id="param_reload_interval" xreflabel="reload_interval">
		<title><varname>reload_interval</varname> (integer)</title>
		<para>
		This parameter represents how many seconds before the data expires (for full caching) the
		automatic reloading is triggered.
		</para>
		<para>
		The default value is <quote>60 s</quote>.
		</para>
		<example>
		<title><varname>reload_interval</varname> parameter usage</title>
		<programlisting format="linespecific">
   
modparam("sql_cacher", "reload_interval", 5)
   
</programlisting>
	    </example>
	</section>
</section>

<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
		<para>
		No function exported to be used from configuration file.
		</para>
</section>

<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_sql_cacher_reload" xreflabel="sql_cacher_reload">
		<title><function moreinfo="none">sql_cacher_reload</function></title>
		<para>
			Reloads the entire SQL table in cache in <emphasis>full caching</emphasis> mode.
		</para>
		<para>
			Reloads the given key or invalidates all the keys in cache in <emphasis>on demand</emphasis> mode.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>id</emphasis> - the caching entry's id
			</para></listitem>
			<listitem><para>
				<emphasis>key</emphasis> (optional) - the specific key to be reloaded, 
				only makes sense in <emphasis>on demand</emphasis> mode.
			</para></listitem>
		</itemizedlist>
		<example>
			<title><function moreinfo="none">sql_cacher_reload</function> usage</title>
			<programlisting format="linespecific">
...
$ opensips-cli -x mi sql_cacher_reload subs_caching
...
$ opensips-cli -x mi sql_cacher_reload subs_caching alice@domain.com
...
</programlisting>
			</example>	
	</section>
</section>
	
<section id="exported_pseudo_variables">
	<title>Exported Pseudo-Variables</title>
		<section id="pv_sql_cached_value" xreflabel="sql_cached_value">
			<title><varname>$sql_cached_value(id{sep}col{sep}key)</varname></title>
			<para>
				The cached data is available through this read-only PV.The format
				is the following:
				<itemizedlist>
					<listitem><para>
					<emphasis>sep</emphasis> : separator configured by
					<xref linkend="param_pvar_delimiter"/>
					</para></listitem>
					<listitem><para>
					<emphasis>id</emphasis>  : cache entry id
					</para></listitem>
					<listitem><para>
					<emphasis>col</emphasis> : name of the required column
					</para></listitem>
					<listitem><para>
					<emphasis>key</emphasis> : value of the <quote>key</quote> column
					</para></listitem>
				</itemizedlist>
			</para>
			<example>
				<title><function moreinfo="none">sql_cached_value(id{sep}col{sep}key) pseudo-variable</function> usage</title>
				<programlisting format="linespecific">
...
$avp(a) = $sql_cached_value(caching_name:column_name_1:key1);
...
				 </programlisting>
			</example>
		</section>

</section>

<section>
	<title>Usage Example</title>
	<para>
	This section provides an usage example for the caching of an SQL table.
	</para>
	<para>
	Suppose one in interested in caching the columns: <quote>host_name</quote>, 
	<quote>reply_code</quote>, <quote>flags</quote> and <quote>next_domain</quote>
	 from the <quote>carrierfailureroute</quote> table of the &osips; database.
	</para>
	<example>
		<title>Example database content - carrierfailureroute table</title>
		<programlisting format="linespecific">
...
+----+---------+-----------+------------+--------+-----+-------------+
| id | domain  | host_name | reply_code | flags | mask | next_domain |
+----+---------+-----------+------------+-------+------+-------------+
|  1 |      99 |           | 408        |    16 |   16 |             |
|  2 |      99 | gw1       | 404        |     0 |    0 | 100         |
|  3 |      99 | gw2       | 50.        |     0 |    0 | 100         |
|  4 |      99 |           | 404        |  2048 | 2112 | asterisk-1  |
+----+---------+-----------+------------+-------+------+-------------+
...
		</programlisting>
	</example>
	<para>
		In the first place, the details of the caching must be provided by setting 
		the module parameter <quote>cache_table</quote> in the &osips; configuration script.
	</para>
	<example>
		<title>Setting the <varname>cache_table</varname> parameter</title>
		<programlisting format="linespecific">
modparam("sql_cacher", "cache_table",
"id=carrier_fr_caching
db_url=mysql://root:opensips@localhost/opensips
cachedb_url=mongodb:mycluster://127.0.0.1:27017/my_db.col
table=carrierfailureroute
key=id
columns=host_name reply_code flags next_domain")
		</programlisting>
	</example>
	<para>
		Next, the values of the cached columns ca be accessed through the <quote>$sql_cached_value</quote> PV.
	</para>
	<example>
		<title>Accessing cached values</title>
		<programlisting format="linespecific">
...
$avp(rc1) = $sql_cached_value(carrier_fr_caching:reply_code:1);
$avp(rc2) = $sql_cached_value(carrier_fr_caching:reply_code:2);
...
var(some_id)=4;
$avp(nd) = $sql_cached_value(carrier_fr_caching:next_domain:$var(some_id));
...
xlog("host name is: $sql_cached_value(carrier_fr_caching:host_name:2)");
...
		</programlisting>
	</example>
</section>

</chapter>