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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module is an implementation of a cache system designed to work with a 
		regular SQL-based server. It uses the internal DB interface to connect
		to the back-end, and also implements the Key-Value interface exported from the core.
	</para>
	<para>
	</para>
	</section>


	<section>
	<title>Advantages</title>
	<para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>memory costs are no longer on the server
				</emphasis>
			</para>
			</listitem>

			<listitem>
			<para>
				<emphasis>the cache is 100% persistent. A restart
					of OpenSIPS server will not affect the DB. The DB is also
				persistent so it can also be restarted without loss of information.</emphasis>
			</para>
			</listitem>

			<listitem>
			<para>
				<emphasis>Multiple OpenSIPS instances can easily share key-value information
				via a regular SQL-based database</emphasis>
			</para>
			</listitem>

		</itemizedlist>
	</para>
	<para>
	</para>
	</section>

	<section>
	<title>Limitations</title>
	
		
		<para>
			<itemizedlist>
			<listitem>
			<para>
			<emphasis>
				The module's counter operations ( ADD and SUB ) are currently only 
				supported by MySQL
		</emphasis>
			</para>
			</listitem>

		</itemizedlist>
		</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		None.
		</para>
	</section>
	
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none:</emphasis>
			</para>
			
			</listitem>
			</itemizedlist>
	</section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_cachedb_url" xreflabel="cachedb_url">
		<title><varname>cachedb_url</varname> (string)</title>
		<para>
			The url of the Database  that OpenSIPS will connect to in order
			to use the from script cache_store,cache_fetch, etc operations.
		</para>

		<para>
			The format to follow is : sql:[conn_id]-dburl
		</para>
		
		<para>
			The parameter can be set multiple times to create multiple connections accessible from the OpenSIPS script.
		</para>
		
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "cachedb_url", "sql:1st-mysql://root:vlad@localhost/opensips_sql")
...
	</programlisting>
		</example>
		
		<example>
		<title>Usage example </title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "cachedb_url", "sql:1st-mysql://root:vlad@localhost/opensips_sql")
modparam("cachedb_sql", "cachedb_url", "sql:2nd-postgres://root:vlad@localhost/opensips_pg")
...
...
cache_store("sql:1st-mysql","key","$ru value");
cache_store("sql:2nd-postgres","counter","10");
...
	</programlisting>
		</example>
	</section>

		<section id="param_db_table" xreflabel="db_table">
		<title><varname>db_table</varname> (string)</title>
		<para>
			The table of the Database  that OpenSIPS will connect to in order
			to use the from script cache_store,cache_fetch, etc operations.
		</para>
		
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "db_table","my_table");
...
	</programlisting>
		</example>
	</section>

		<section id="param_key_column" xreflabel="key_column">
		<title><varname>key_column</varname> (string)</title>
		<para>
			The column where the key will be stored
		</para>
		
		<example>
		<title>Set <varname>key_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "key_column","some_name");
...
	</programlisting>
		</example>
	</section>

		<section id="param_value_column" xreflabel="value_column">
		<title><varname>value_column</varname> (string)</title>
		<para>
			The column where the value will be stored
		</para>
		
		<example>
		<title>Set <varname>value_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "value_column","some_name");
...
	</programlisting>
		</example>
	</section>

		<section id="param_counter_column" xreflabel="counter_column">
		<title><varname>counter_column</varname> (string)</title>
		<para>
			The column where the counter value will be stored
		</para>
		
		<example>
		<title>Set <varname>counter_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "counter_column","some_name");
...
	</programlisting>
		</example>
	</section>

		<section id="param_expires_column" xreflabel="expires_column">
		<title><varname>expires_column</varname> (string)</title>
		<para>
			The column where the expires will be stored
		</para>
		
		<example>
		<title>Set <varname>expires_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "expires_column","some_name");
...
	</programlisting>
		</example>
	</section>

		<section id="param_cache_clean_period" xreflabel="cache_clean_period">
		<title><varname>cache_clean_period</varname> (int)</title>
		<para>
			The interval in seconds at which the expired keys will be removed from
			the database. Default value is 60 ( seconds )
		</para>
		
		<example>
		<title>Set <varname>cache_clean_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_sql", "cache_clean_period",10);
...
	</programlisting>
		</example>
	</section>
	
	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<para>The module does not export functions to be used
		in configuration script.</para>
	</section>	


</section>

</chapter>

