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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This is a module which provides MySQL connectivity for OpenSIPS.
		It implements the DB API defined in OpenSIPS.
	</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>If a <xref linkend="param_use_tls"/> is defined, the <emphasis role='bold'>tls_mgm</emphasis> module will need to be loaded as well</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</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:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libmysqlclient-dev</emphasis> - the development libraries of mysql-client.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_exec_query_threshold" xreflabel="exec_query_threshold">
		<title><varname>exec_query_threshold</varname> (integer)</title>
		<para>
		If queries take longer than 'exec_query_threshold' microseconds, warning
		messages will be written to logging facility.
		</para>
		<para>
		<emphasis>
			Default value is 0 - disabled.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>exec_query_threshold</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_mysql", "exec_query_threshold", 60000)
...
</programlisting>
		</example>
	</section>
		<section id="param_timeout_interval" xreflabel="timeout_interval">
		<title><varname>timeout_interval</varname> (integer)</title>
		<para>
		Time interval after which a connection attempt (read or write request)
		is aborted. The value counts three times, as several retries are done
		from the driver before it gives up.
		</para>
		<para>
		The read timeout parameter is ignored on driver versions prior to
		<quote>5.1.12</quote>, <quote>5.0.25</quote> and <quote>4.1.22</quote>.
		The write timeout parameter is ignored on version prior to <quote>5.1.12</quote>
		and <quote>5.0.25</quote>, the <quote>4.1</quote> release don't support it at all.
		</para>
		<para>
		<emphasis>
			Default value is 2 (6 sec).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timeout_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_mysql", "timeout_interval", 2)
...
</programlisting>
		</example>
	</section>
        <section id="param_max_db_queries" xreflabel="max_db_queries">
		<title><varname>max_db_queries</varname> (integer)</title>
		<para>
            The maximum number of retries to execute a failed query due to connections problems.
            If this parameter is set improperly, it is set to default value.
		</para>
		<para>
		<emphasis>
			Default value is 2.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_db_queries</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_mysql", "max_db_queries", 2)
...
</programlisting>
		</example>
	</section>

        <section id="param_max_db_retries" xreflabel="max_db_retries">
		<title><varname>max_db_retries</varname> (integer)</title>
		<para>
		The maximum number of database connection retries. If this parameter
                is set improperly, it is set to default value. 
		</para>
		<para>
		<emphasis>
			Default value is 3.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_db_retries</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_mysql", "max_db_retries", 2)
...
</programlisting>
		</example>
	</section>

        <section id="param_ps_max_col_size" xreflabel="ps_max_col_size">
		<title><varname>ps_max_col_size</varname> (integer)</title>
		<para>
		The maximum size of a column's data, when fetched using prepared
		statements.  Particularly relevant for variable-length data, such as
		CHAR, BLOB, etc.
		</para>
		<para>
		NOTE: Should a column's data exceed this limit, the value will be
		silently truncated to fit the buffer, without reporting any errors!
		</para>
		<para>
		<emphasis>
			Default value is <emphasis>1024 (bytes)</emphasis>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>ps_max_col_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_mysql", "ps_max_col_size", 4096)
...
</programlisting>
		</example>
	</section>

        <section id="param_use_tls" xreflabel="use_tls">
		<title><varname>use_tls</varname> (integer)</title>
		<para>
		Setting this parameter will allow you to use TLS for MySQL connections.
		In order to enable TLS for a specific connection, you can use the
		"<emphasis role='bold'>tls_domain=</emphasis>dom_name" URL parameter in the db_url of
		the respective OpenSIPS module. This should be placed at the end of the
		URL after the <emphasis role='bold'>'?'</emphasis> character. Additionally,
		the query string may include the "<emphasis role='bold'>tls_opts=</emphasis>
		PKEY,CERT,CA,CA_DIR,CIPHERS" CSV parameter, in order to control/limit the
		amount of TLS options passed to the TLS library.
		</para>
		<para>
		When using this parameter, you must also ensure that
		<emphasis>tls_mgm</emphasis> is loaded and properly configured. Refer to
		the the module for additional info regarding TLS client domains.
		</para>
		<para>
		Note that if you want to use this feature, the TLS domain must be
		provisioned in the configuration file, <emphasis>NOT</emphasis> in
		the database. In case you are loading TLS certificates from the
		database, you must at least define one domain in the
		configuration script, to use for the initial connection to the DB.
		</para>
		<para>
		Also, you can <emphasis>NOT</emphasis> enable TLS for the connection
		to the database of the <emphasis>tls_mgm</emphasis> module itself.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis role='bold'>0</emphasis> (not enabled)
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>use_tls</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tls_mgm", "client_domain", "dom1")
modparam("tls_mgm", "certificate", "[dom1]/etc/pki/tls/certs/opensips.pem")
modparam("tls_mgm", "private_key", "[dom1]/etc/pki/tls/private/opensips.key")
modparam("tls_mgm", "ca_list",     "[dom1]/etc/pki/tls/certs/ca.pem")
...
modparam("db_mysql", "use_tls", 1)
...
modparam("usrloc", "db_url", "mysql://root:1234@localhost/opensips?tls_domain=dom1")
...
modparam("usrloc", "db_url", "mysql://root:1234@localhost/opensips?tls_domain=dom1&amp;tls_opts=PKEY,CERT,CA,CA_DIR,CIPHERS")
...
</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>
	<title>Installation</title>
		<para>
		Because it dependes on an external library, the mysql module is not
		compiled and installed by default. You can use one of the next options.
		</para>
		<itemizedlist>
			<listitem>
			<para>
			- edit the "Makefile" and remove "db_mysql" from "excluded_modules"
			list. Then follow the standard procedure to install &osips;:
			"make all; make install".
			</para>
			</listitem>
			<listitem>
			<para>
			- from command line use: 'make all include_modules="db_mysql";
			make install include_modules="db_mysql"'.
			</para>
			</listitem>
		</itemizedlist>
	</section>

	<section id="exported_events" xreflabel="Exported Events">
	<title>Exported Events</title>
	<section id="event_E_MYSQL_CONNECTION" xreflabel="E_MYSQL_CONNECTION">
		<title>
		<function moreinfo="none">E_MYSQL_CONNECTION</function>
		</title>
		<para>
			This event is raised when a MySQL connection is lost or recovered.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
					<emphasis>url</emphasis> - the URL of the connection as specified by the <emphasis>db_url</emphasis> parameter.
			</para></listitem>
			<listitem><para>
				<emphasis>status</emphasis> - <emphasis>connected</emphasis> if the connection recovered, or 
				<emphasis>disconnected</emphasis> if the connection was lost.
			</para></listitem>
		</itemizedlist>
	</section>
	</section>

</chapter>

