README

pgmemcache 2.0
================

pgmemcache is a set of PostgreSQL user-defined functions that provide
an interface to memcached. Installing pgmemcache is easy, but does
have a few trivial requirements.

REQUIREMENTS:
=============

1) libmemcached 0.38 or newer (http://tangent.org/552/libmemcached.html)
2) PostgreSQL 9.1 or newer recommended (http://www.postgresql.org/)

Always prefer the latest versions.

INSTALLATION:
=============

1a) Building from sources:
--------------------------

1) Install PostgreSQL with PGXS (if not already installed)
2) Install libmemcached
3) make
4) sudo make install

If necessary, update LD_LIBRARY_CACHE for the PostgreSQL server owner and restart PostgreSQL.
Also make sure that the pg_config binary is in your PATH (or edit the Makefile).

1 b) Building on Debian:
------------------------

1) sudo make build-dep
2) make deb9.2
3) sudo dpkg -i ../postgresql-pgmemcache-*.deb

SETUP (run this for all databases you want to use pgmemcache in):
=================================================================

::

    % psql <mydbname> -c 'create extension pgmemcache'

It is often more convenient to specify a list of memcached servers
to connect to in postgresql.conf, rather than calling memcache_server_add()
in each new client connection. This can be done as follows:

    1. Edit postgresql.conf
    2. Append "pgmemcache" to shared_preload_libraries
    3. Append "pgmemcache" to custom_variable_classes

    (Optional parts)

    4. Set the "pgmemcache.default_servers" custom GUC variable to a
       comma-separated list of 'host:port' pairs (the port is optional).
    5. Set the pgmemcache.default_behavior flags to suit your needs. The format is a
       comma-separated list of memcached behavior (optional) of behavior_flag:behavior_data.
       The flags correspond with libmemcached behavior flags. Check the libmemcached
       documentation for those. As an example behavior you might have a line like:

       pgmemcache.default_behavior='BINARY_PROTOCOL:1'

       in your postgresql.conf

In case your system has SELinux please run:

/usr/bin/checkmodule -M -m -o pgmemcache.mod pgmemcache.te
/usr/bin/semodule_package -o pgmemcache.pp -m pgmemcache.mod
/usr/sbin/semodule -i pgmemcache.pp

USAGE:
======

**memcache_server_add('hostname:port'::TEXT)**

**memcache_server_add('hostname'::TEXT)**

Adds a server to the list of available servers. If the port is not specified,
the libmemcache default port (11211) is used. This should only be done in one
central place in the code (normally wrapped in an IF statement).

**memcache_add(key::TEXT, value::TEXT, expire::TIMESTAMPTZ)**

**memcache_add(key::TEXT, value::TEXT, expire::INTERVAL)**

**memcache_add(key::TEXT, value::TEXT)**

Adds a key to the cache cluster, if the key does not already exist.

**newval = memcache_decr(key::TEXT, decrement::INT4)**

**newval = memcache_decr(key::TEXT)**

If key exists and is an integer, atomically decrements by the value specified
(default decrement is one).  Returns INT value after decrement.

**memcache_delete(key::TEXT, hold_timer::INTERVAL)**

**memcache_delete(key::TEXT)**

Deletes a given key. If a hold timer is specified, key with the same name can't
be added until the hold timer expires.

**memcache_flush_all()**

Flushes all data on all servers in the memcache cluster.

**value = memcache_get(key::TEXT)**

Fetches a key out of the cache. Returns NULL if the key does not exist; otherwise,
it returns the value of the key as TEXT. Note that zero-length values are allowed.

**memcache_get_multi (keys::TEXT[])**

**memcache_get_multi (keys::BYTEA[])**

Fetches an ARRAY of keys from the cache, returns a list of RECORDs
for the found keys, with the columns titled key and value.

**newval = memcache_incr(key::TEXT, increment::INT4)**

**newval = memcache_incr(key::TEXT)**

If key exists and is an integer, atomically increment by the value specified
(the default increment is one).  Returns INT value after increment.

**memcache_replace(key::TEXT, value::TEXT, expire::TIMESTAMPTZ)**

**memcache_replace(key::TEXT, value::TEXT, expire::INTERVAL)**

**memcache_replace(key::TEXT, value::TEXT)**

Replaces an existing key's value if the key already exists.

**memcache_set(key::TEXT, value::TEXT, expire::TIMESTAMPTZ)**

**memcache_set(key::TEXT, value::TEXT, expire::INTERVAL)**

**memcache_set(key::TEXT, value::TEXT)**

Regardless of whether the specified key already exists, set its
current value to "value", replacing the previous value if any.

**stats = memcache_stats()**

Returns a TEXT string with all of the stats from all servers in the server list.
Statistics are derived from a summation of the statistics of all the servers in
the server list.

EXAMPLES:
=========

Most installations will need a few functions to allow pgmemcache to work correctly.
Here are a few example functions that should get most people off the ground and running:

SET search_path = public;

The following function is an example of a trigger function that is used to
replace the value of something in the cache with its new value.
::

	CREATE OR REPLACE FUNCTION auth_passwd_upd() RETURNS TRIGGER AS $$
		BEGIN
		IF OLD.passwd != NEW.passwd THEN
			PERFORM memcache_replace('user_id_' || NEW.user_id || '_password', NEW.passwd);
		END IF;
		RETURN NEW;
	END;
	$$ LANGUAGE 'plpgsql';

Activate the trigger for UPDATEs.

CREATE TRIGGER auth_passwd_upd_trg AFTER UPDATE ON passwd FOR EACH ROW EXECUTE PROCEDURE auth_passwd_upd();

The above is not transaction safe, however.  A better approach is to have pgmemcache
invalidate the cached data, but not replace it.
::

	CREATE OR REPLACE FUNCTION auth_passwd_upd() RETURNS TRIGGER AS $$
	BEGIN
		IF OLD.passwd != NEW.passwd THEN
			PERFORM memcache_delete('user_id_' || NEW.user_id || '_password');
		END IF;
		RETURN NEW;
	END;$$ LANGUAGE 'plpgsql';

Here's an example delete trigger::

	CREATE OR REPLACE FUNCTION auth_passwd_del() RETURNS TRIGGER AS $$
	BEGIN
		PERFORM memcache_delete('user_id_' || NEW.user_id || '_password');
		RETURN OLD;
	END;
	$$ LANGUAGE 'plpgsql';

Activate the trigger for DELETEs

CREATE TRIGGER auth_passwd_del_trg AFTER DELETE ON passwd FOR EACH ROW EXECUTE PROCEDURE auth_passwd_del();

LICENSE:
========

pgmemcache is released under an MIT-style license (BSD without advertising
clause). For the exact license terms, see the file "COPYING".

CONTACT:
========

Bug reports and patches are very welcome, either submitted via the
PgFoundry web interface (http://pgfoundry.org/projects/pgmemcache),
or sent via email to <hannu.valtonen@ormod.com>.

HISTORY:
========

pgmemcache was originally written by Sean Chittenden. During version
1.1 times it was maintained by Neil Conway. Since version 2.0 pgmemcache
was rewritten to work on top of libmemcached and the maintainership
moved to Hannu Valtonen.

During version 1.x series starting from 1.1, development of pgmemcache
was sponsored by the Open Technology Group, Inc. (OTG).
OTG provides training in a wide range of open source software, including
pgmemcache and PostgreSQL training. For more information, see http://www.otg-nc.com/

THANKS:
=======

Suzuki Hironobu contributed major patches for the 2.0 series, among other
things, support for libmemcached configuration settings.