pgpool2.git / summary / log / commit / refs
commit 338c971a0afa6037e1d20d802e908d9628ee37ca
Author: Muhammad Usama <m.usama@gmail.com>
Date: Mon Oct 10 19:38:44 2016 +0000
SGML docs for in memory query cache
doc/src/sgml/loadbalance.sgml | 4 +-
doc/src/sgml/memcache.sgml | 444 +++++++++++++++++++++++++++++++++++++++++-
2 files changed, 445 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/loadbalance.sgml b/doc/src/sgml/loadbalance.sgml
index 4b3ca0ebb..bca5e4ff8 100644
--- a/doc/src/sgml/loadbalance.sgml
+++ b/doc/src/sgml/loadbalance.sgml
@@ -60,7 +60,7 @@
</para>
<para>
You can use regular expression into the list to match function name
- (to which added automatically ^ and $),
+ (to which ^ and $ are automatically added),
</para>
<example id="example-white-function-list-1">
@@ -97,7 +97,7 @@ white_function_list = 'get_.*,select_.*'
</para>
<para>
You can use regular expression into the list to match function name
- (to which added automatically ^ and $),
+ (to which ^ and $ are automatically added),
</para>
<example id="example-black-function-list-1">
diff --git a/doc/src/sgml/memcache.sgml b/doc/src/sgml/memcache.sgml
index feae13f61..d3a501425 100644
--- a/doc/src/sgml/memcache.sgml
+++ b/doc/src/sgml/memcache.sgml
@@ -4,6 +4,448 @@
<title>In Memory Query Cache</title>
<para>
- memory_cache_enabled etc.
+ In memory query cache can be used with all modes of
+ <productname>Pgpool-II</productname>. It is different
+ from the query cache on the point that in memory query
+ cache is faster because of the in memory nature of the storage.
+ Moreover <productname>Pgpool-II</productname> does not
+ need a restart when the cache gets outdated because of
+ the underlying table updates.
</para>
+ <para>
+ In memory cache saves the pair of SELECT statement
+ and its result
+ (along with the Bind parameters, if the SELECT is an
+ extended query). If the same SELECTs comes in,
+ <productname>Pgpool-II</productname> returns the value
+ from cache. Since no <acronym>SQL</acronym> parsing nor
+ access to PostgreSQL are involved, the serving of results
+ from the in memory cache is extremely fast.
+ </para>
+ <para>
+ On the other hand, it might be slower than the normal path
+ in some cases, because it adds some overhead to store cache.
+ Moreover when a table is updated, <productname>Pgpool-II
+ </productname> automatically deletes all the caches related
+ to the table. So the performance will be degraded by a system
+ with a lot of updates.
+ If the cache_hit_ratio is lower than 70%, you might want
+ to disable in memory cache.
+ </para>
+
+ <sect2 id="runtime-in-memory-query-cache-enabling">
+ <title>Enabling in memory query cache</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-memory-cache-enabled" xreflabel="memory_cache_enabled">
+ <term><varname>memory_cache_enabled</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>memory_cache_enabled</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Setting to on enables the memory cache.
+ Default is off.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-in-memory-query-cache-choose-storage">
+ <title>Choosing cache storage</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-memqcache-method" xreflabel="memqcache_method">
+ <term><varname>memqcache_method</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>memqcache_method</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the storage type to be used for the cache.
+ Below table contains the list of all valid values for the parameter.
+ </para>
+
+ <table id="memqcache-method-table">
+ <title>Memcache method options</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>'shmem'</literal></entry>
+ <entry>Use shared memory</entry>
+ </row>
+
+ <row>
+ <entry><literal>'memcached'</literal></entry>
+ <entry>Use <ulink url="http://memcached.org/">memcached</ulink></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Default is 'shmem'.
+ </para>
+
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-in-memory-query-cache-config">
+ <title>Common configurations</title>
+ <para>
+ These below parameter are valid for both <literal>shmem</literal>
+ and <literal>memcached</literal> type query cache.
+ </para>
+ <variablelist>
+
+ <varlistentry id="guc-memqcacheexpire" xreflabel="memqcache_expire">
+ <term><varname>memqcache_expire</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>memqcache_expire</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the life time of query cache in seconds.
+ Default is 0. which means no cache expiration and cache remains
+ valid until the table is updated.
+ </para>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+
+ <note>
+ <para>
+ This parameters <xref linkend="guc-memqcacheexpire"> and
+ <xref linkend="guc-memqcache-auto-cache-invalidation"> are orthogonal to each other.
+ </para>
+ </note>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-memqcache-auto-cache-invalidation" xreflabel="memqcache_auto_cache_invalidation">
+ <term><varname>memqcache_auto_cache_invalidation</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>memqcache_auto_cache_invalidation</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Setting to on, automatically deletes the cache related to the updated tables.
+ When off, cache is not deleted.
+ </para>
+ <para>
+ Default is on.
+ </para>
+ <note>
+ <para>
+ This parameters <xref linkend="guc-memqcache-auto-cache-invalidation">
+ and <xref linkend="guc-memqcacheexpire"> are orthogonal to each other.
+ </para>
+ </note>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-memqcache-maxcache" xreflabel="memqcache_maxcache">
+ <term><varname>memqcache_maxcache</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>memqcache_maxcache</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the maximum size in bytes of the SELECT query result to be cached.
+ The result with data size larger than this value will not be cached by
+ <productname>Pgpool-II</productname>.
+ And when the caching of data is rejected because of the size constraint the following
+ message is shown.
+ <programlisting>
+LOG: pid 13756: pool_add_temp_query_cache: data size exceeds memqcache_maxcache. current:4095 requested:111 memq_maxcache:4096
+ </programlisting>
+ </para>
+ <note>
+ <para>
+ For the shared memory query(<literal>'shmem'</literal>) cache the
+ <varname>memqcache_maxcache</varname> must be set lower than
+ <xref linkend="guc-memqcache-cache-block-size"> and for <literal>'memcached'</literal>
+ it must be lower than the size of slab (default is 1 MB).
+ </para>
+ </note>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-white-memqcache-table-list" xreflabel="white_memqcache_table_list">
+ <term><varname>white_memqcache_table_list</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>white_memqcache_table_list</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+
+ <para>
+ Specifies a comma separated list of table names whose SELECT
+ results should be cached by the <productname>Pgpool-II</productname>.
+ </para>
+
+ <para>
+ You can use regular expression into the list to match table name
+ (to which ^ and $ are automatically added),
+ </para>
+
+ <note>
+ <para>
+ If the queries can refer the table with and without the schema
+ qualification then you must add both entries(with and without
+ schema name) in the list.
+ <programlisting>
+#For example:
+#If the queries sometime use "table1" and other times "public.table1"
+#to refer the table1 then the white_memqcache_table_list
+#would be configured as follows.
+
+white_memqcache_table_list = "table1,public.table1"
+
+ </programlisting>
+
+ </para>
+ </note>
+ <note>
+ <para>
+ <varname>white_memqcache_table_list</varname> white_memqcache_table_list takes
+ precedence over <xref linkend="guc-black-memqcache-table-list">
+ </para>
+ </note>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-black-memqcache-table-list" xreflabel="black_memqcache_table_list">
+ <term><varname>black_memqcache_table_list</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>black_memqcache_table_list</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies a comma separated list of table names whose SELECT
+ results should <emphasis>NOT</emphasis> be cached by the <productname>
+ Pgpool-II</productname>.
+ </para>
+
+ <para>
+ You can use regular expression into the list to match table name
+ (to which ^ and $ are automatically added),
+ </para>
+
+ <note>
+ <para>
+ If the queries can refer the table with and without the schema
+ qualification then you must add both entries(with and without
+ schema name) in the list.
+ <programlisting>
+#For example:
+#If the queries sometime use "table1" and other times "public.table1"
+#to refer the table1 then the black_memqcache_table_list
+#would be configured as follows.
+
+black_function_list = "table1,public.table1"
+
+ </programlisting>
+
+ </para>
+ </note>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-memqcache-oiddir" xreflabel="memqcache_oiddir">
+ <term><varname>memqcache_oiddir</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>memqcache_oiddir</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the full path to the directory for storing the
+ <literal>oids</literal> of tables used by SELECT queries.
+ </para>
+ <para>
+ <varname>memqcache_oiddir</varname> directory contains the sub directories
+ for the databases. The directory name is the OID of the database, And each
+ database directory contains the files for each table used by SELECT statement.
+ Again the name of the file is the OID of the table.
+ These files contains the pointers to query cache which are used as key for
+ deleting the caches.
+ </para>
+ <note>
+ <para>
+ Normal restart of <productname>Pgpool-II</productname> does not clear the
+ contents of <varname>memqcache_oiddir</varname>.
+ </para>
+ </note>
+ <para>
+ This parameter can be changed by reloading the pgpool configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-in-memory-query-cache-shmem-config">
+ <title>Configurations to use shared memory</title>
+
+ <para>
+ These are the parameters used with shared memory as the cache storage.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="guc-memqcache-total-size" xreflabel="memqcache_total_size">
+ <term><varname>memqcache_total_size</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>memqcache_total_size</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the shared memory cache size in bytes.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-memqcache-max-num-cache" xreflabel="memqcache_max_num_cache">
+ <term><varname>memqcache_max_num_cache</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>memqcache_max_num_cache</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the number of cache entries. This is used to define the size of cache management space.
+ </para>
+ <note>
+ <para>
+ The management space size can be calculated by:
+ <varname>memqcache_max_num_cache</varname> * 48 bytes.
+ Too small number will cause an error while registering cache.
+ On the other hand too large number will just waste space.
+ </para>
+ </note>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-memqcache-cache-block-size" xreflabel="memqcache_cache_block_size">
+ <term><varname>memqcache_cache_block_size</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>memqcache_cache_block_size</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the cache block size. <productname>Pgpool-II</productname> uses the
+ cache memory arranged in <varname>memqcache_cache_block_size</varname> blocks.
+ SELECT result is packed into the block and must fit in a single block.
+ And the results larger than <varname>memqcache_cache_block_size</varname> are
+ not cached.
+ </para>
+
+ <para>
+ <varname>memqcache_cache_block_size</varname> must be set to atleast 512.
+ </para>
+
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-in-memory-query-cache-memcached-config">
+ <title>Configurations to use memcached</title>
+
+ <para>
+ These are the parameters used with memcached as the cache storage.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="guc-memqcache-memcached-host" xreflabel="memqcache_memcached_host">
+ <term><varname>memqcache_memcached_host</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>memqcache_memcached_host</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the host name or the IP address on which <literal>memcached</literal>
+ works. You can use <literal>'localhost'</literal> if <literal>memcached</literal>
+ and <productname>Pgpool-II</productname> resides on same server.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-memqcache-memcached-port" xreflabel="memqcache_memcached_port">
+ <term><varname>memqcache_memcached_port</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>memqcache_memcached_port</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the port number of <acronym>memcached</acronym>.
+ Default is 11211.
+ </para>
+ <para>
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
</sect1>
[parent: fe69d818c9e2]