upstream/1.0/README.pgmemcache

# $PostgreSQL: pgmemcache/README.pgmemcache,v 1.6 2004/12/25 03:00:15 seanc Exp $

Installing pgmemcache is easy, but does have a few trivial
requirements.


REQUIREMENTS:

*) libmemcache(3) 1.1.0 or newer.

   http://people.FreeBSD.org/~seanc/libmemcache/

*) pmk(1)

   http://pmk.sf.net/

*) PostgreSQL 8.0 rc2 or newer.  pgmemcache may work on older versions
   of PostgreSQL, but will likely have to be compiled by
   hand.

   http://www.PostgreSQL.org/


INSTALLATION:

        Substitute 'gmake' with whatever GNU make's name is on your
        platform (normally gmake, gnumake, or make).

        % pmk   (or `pmk -e debug` for debugging info)
        % gmake
        % sudo gmake install


SETUP:

        The path below is the path for FreeBSD, it may be something
        different on your operating system.  The path is shown above
        during the `sudo gmake install` step: look in the output above
        if you're having problems.

        % psql [mydbname] [pguser]
        [mydbname]=# BEGIN;
        [mydbname]=# \i /usr/local/share/postgresql/contrib/pgmemcache.sql
        [mydbname]=# COMMIT;

API:

memcache_init()
        Initializes the backend to work with memcached(8).  Returns
        TRUE if this call initialized itself (ie, servers need to be
        added).  See the mc_init() example below for ideas on how this
        is used.

memcache_server_add(/* server name */ TEXT, /* port */ TEXT)
        Adds a server to the list of available servers.  This should
        only be done in one central place in the code (normally
        wrapped in an IF statement).  See the mc_init() example below
        for ideas on how this is used.

memcache_server_find(/* hash */ INT4)
        Returns the hostname:port of the server assigned the hash value

memcache_server_find(/* key */ TEXT)
        Returns the hostname:port of the server containing the specified key

memcache_add(/* key */ TEXT, /* value */ TEXT, /* expire */ INTERVAL, /* flags */ INT2)
memcache_add(/* key */ TEXT, /* value */ TEXT, /* expire */ INTERVAL)
memcache_add(/* key */ TEXT, /* value */ TEXT)
memcache_add(/* key */ TEXT, /* value */ TEXT, /* expire */ TIMESTAMP WITH TIME ZONE, /* flags */ INT2)
memcache_add(/* key */ TEXT, /* value */ TEXT, /* expire */ TIMESTAMP WITH TIME ZONE)
        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 not be added until the hold timer expires.

memcache_flush_all()
        Flushes all data on all servers in the memcache cluster.

memcache_flush(/* key */ TEXT)
        Flushes all keys from the backend that the given key maps to.

memcache_free()
        Cleans up and frees all data allocated by libmemcache(3).

value = memcache_get(/* key */ TEXT)
        Fetches a key out of the cache.  Returns a TEXT for keys that
        are found and NULL for keys that didn't exist. Zero length
        values are valid.

hash = memcache_hash(/* key */ TEXT)
        Returns the hash value for a given key

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 (default increment is one).  Returns INT value
        after increment.

memcache_replace(/* key */ TEXT, /* value */ TEXT, /* expire */ INTERVAL, /* flags */ INT2)
memcache_replace(/* key */ TEXT, /* value */ TEXT, /* expire */ INTERVAL)
memcache_replace(/* key */ TEXT, /* value */ TEXT)
memcache_replace(/* key */ TEXT, /* value */ TEXT, /* expire */ TIMESTAMP WITH TIME ZONE, /* flags */ INT2)
memcache_replace(/* key */ TEXT, /* value */ TEXT, /* expire */ TIMESTAMP WITH TIME ZONE)
        Replaces an existing key's s value if the key already exists.

memcache_set(/* key */ TEXT, /* value */ TEXT, /* expire */ INTERVAL, /* flags */ INT2)
memcache_set(/* key */ TEXT, /* value */ TEXT, /* expire */ INTERVAL)
memcache_set(/* key */ TEXT, /* value */ TEXT)
memcache_set(/* key */ TEXT, /* value */ TEXT, /* expire */ TIMESTAMP WITH TIME ZONE, /* flags */ INT2)
memcache_set(/* key */ TEXT, /* value */ TEXT, /* expire */ TIMESTAMP WITH TIME ZONE)
        Regardless of whether the key to the specified value.

stats = memcache_stats()
        Returns a TEXT string with all of the stats from all servers
        in the server list.

stat = memcache_stats(/* statistic key */ TEXT)
        Returns a specific statistic as a TEXT object. Statistic
        derived from summation of all servers in 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:

-- The following function is required to build the server list.  This
-- function should be small as it will be called constantly.
-- memcache_init() returns FALSE if it did not need to perform any
-- memory initialization.  This allows us to only add servers if we're
-- setting up the global server list.  If you're having problems,
-- check your search_path for the memcache_*() functions and make sure
-- you add it to your environment.
SET search_path = public;
CREATE OR REPLACE FUNCTION mc_init() RETURNS VOID AS 'BEGIN
        IF memcache_init() THEN
                PERFORM memcache_server_add(''mc1.example.com'', ''11211'');
                PERFORM memcache_server_add(''mc2.example.com'', ''11211'');
        END IF;
        RETURN;
END;' LANGUAGE 'plpgsql';

-- 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_trg_upd() RETURNS TRIGGER  AS 'BEGIN
        IF OLD.passwd != NEW.passwd THEN
                PERFORM mc_init();
                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_trg_upd() RETURNS TRIGGER  AS 'BEGIN
        IF OLD.passwd != NEW.passwd THEN
                PERFORM mc_init();
                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_trg_del() RETURNS TRIGGER  AS 'BEGIN
        PERFORM mc_init();
        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();


USAGE:

See the presentation at:

http://people.FreeBSD.org/~seanc/pgmemcache/pgmemcache.pdf

for additional instructions, examples (page 16-17), and ideas.


QUESTIONS/SUPPORT/BUGS:

Send email to sean@chittenden.org.
1	dpavlin	2	# $PostgreSQL: pgmemcache/README.pgmemcache,v 1.6 2004/12/25 03:00:15 seanc Exp $
2
3			Installing pgmemcache is easy, but does have a few trivial
4			requirements.
5
6
7			REQUIREMENTS:
8
9			*) libmemcache(3) 1.1.0 or newer.
10
11			http://people.FreeBSD.org/~seanc/libmemcache/
12
13			*) pmk(1)
14
15			http://pmk.sf.net/
16
17			*) PostgreSQL 8.0 rc2 or newer. pgmemcache may work on older versions
18			of PostgreSQL, but will likely have to be compiled by
19			hand.
20
21			http://www.PostgreSQL.org/
22
23
24			INSTALLATION:
25
26			Substitute 'gmake' with whatever GNU make's name is on your
27			platform (normally gmake, gnumake, or make).
28
29			% pmk (or `pmk -e debug` for debugging info)
30			% gmake
31			% sudo gmake install
32
33
34			SETUP:
35
36			The path below is the path for FreeBSD, it may be something
37			different on your operating system. The path is shown above
38			during the `sudo gmake install` step: look in the output above
39			if you're having problems.
40
41			% psql [mydbname] [pguser]
42			[mydbname]=# BEGIN;
43			[mydbname]=# \i /usr/local/share/postgresql/contrib/pgmemcache.sql
44			[mydbname]=# COMMIT;
45
46			API:
47
48			memcache_init()
49			Initializes the backend to work with memcached(8). Returns
50			TRUE if this call initialized itself (ie, servers need to be
51			added). See the mc_init() example below for ideas on how this
52			is used.
53
54			memcache_server_add(/* server name / TEXT, / port */ TEXT)
55			Adds a server to the list of available servers. This should
56			only be done in one central place in the code (normally
57			wrapped in an IF statement). See the mc_init() example below
58			for ideas on how this is used.
59
60			memcache_server_find(/* hash */ INT4)
61			Returns the hostname:port of the server assigned the hash value
62
63			memcache_server_find(/* key */ TEXT)
64			Returns the hostname:port of the server containing the specified key
65
66			memcache_add(/* key / TEXT, / value / TEXT, / expire / INTERVAL, / flags */ INT2)
67			memcache_add(/* key / TEXT, / value / TEXT, / expire */ INTERVAL)
68			memcache_add(/* key / TEXT, / value */ TEXT)
69			memcache_add(/* key / TEXT, / value / TEXT, / expire / TIMESTAMP WITH TIME ZONE, / flags */ INT2)
70			memcache_add(/* key / TEXT, / value / TEXT, / expire */ TIMESTAMP WITH TIME ZONE)
71			Adds a key to the cache cluster if the key does not already
72			exist.
73
74			newval = memcache_decr(/* key / TEXT, / decrement */ INT4)
75			newval = memcache_decr(/* key */ TEXT)
76			If key exists and is an integer, atomically decrements by the
77			value specified (default decrement is one). Returns INT value
78			after decrement.
79
80			memcache_delete(/* key / TEXT, / hold timer */ INTERVAL)
81			memcache_delete(/* key */ TEXT)
82			Deletes a given key. If a hold timer is specified, key with
83			the same name can not be added until the hold timer expires.
84
85			memcache_flush_all()
86			Flushes all data on all servers in the memcache cluster.
87
88			memcache_flush(/* key */ TEXT)
89			Flushes all keys from the backend that the given key maps to.
90
91			memcache_free()
92			Cleans up and frees all data allocated by libmemcache(3).
93
94			value = memcache_get(/* key */ TEXT)
95			Fetches a key out of the cache. Returns a TEXT for keys that
96			are found and NULL for keys that didn't exist. Zero length
97			values are valid.
98
99			hash = memcache_hash(/* key */ TEXT)
100			Returns the hash value for a given key
101
102			newval = memcache_incr(/* key / TEXT[, / increment */ INT4])
103			newval = memcache_incr(/* key */ TEXT)
104			If key exists and is an integer, atomically increment by the
105			value specified (default increment is one). Returns INT value
106			after increment.
107
108			memcache_replace(/* key / TEXT, / value / TEXT, / expire / INTERVAL, / flags */ INT2)
109			memcache_replace(/* key / TEXT, / value / TEXT, / expire */ INTERVAL)
110			memcache_replace(/* key / TEXT, / value */ TEXT)
111			memcache_replace(/* key / TEXT, / value / TEXT, / expire / TIMESTAMP WITH TIME ZONE, / flags */ INT2)
112			memcache_replace(/* key / TEXT, / value / TEXT, / expire */ TIMESTAMP WITH TIME ZONE)
113			Replaces an existing key's s value if the key already exists.
114
115			memcache_set(/* key / TEXT, / value / TEXT, / expire / INTERVAL, / flags */ INT2)
116			memcache_set(/* key / TEXT, / value / TEXT, / expire */ INTERVAL)
117			memcache_set(/* key / TEXT, / value */ TEXT)
118			memcache_set(/* key / TEXT, / value / TEXT, / expire / TIMESTAMP WITH TIME ZONE, / flags */ INT2)
119			memcache_set(/* key / TEXT, / value / TEXT, / expire */ TIMESTAMP WITH TIME ZONE)
120			Regardless of whether the key to the specified value.
121
122			stats = memcache_stats()
123			Returns a TEXT string with all of the stats from all servers
124			in the server list.
125
126			stat = memcache_stats(/* statistic key */ TEXT)
127			Returns a specific statistic as a TEXT object. Statistic
128			derived from summation of all servers in server list.
129
130
131			EXAMPLES:
132
133			Most installations will need a few functions to allow pgmemcache to
134			work correctly. Here are a few example functions that should get most
135			people off the ground and running:
136
137			-- The following function is required to build the server list. This
138			-- function should be small as it will be called constantly.
139			-- memcache_init() returns FALSE if it did not need to perform any
140			-- memory initialization. This allows us to only add servers if we're
141			-- setting up the global server list. If you're having problems,
142			-- check your search_path for the memcache_*() functions and make sure
143			-- you add it to your environment.
144			SET search_path = public;
145			CREATE OR REPLACE FUNCTION mc_init() RETURNS VOID AS 'BEGIN
146			IF memcache_init() THEN
147			PERFORM memcache_server_add(''mc1.example.com'', ''11211'');
148			PERFORM memcache_server_add(''mc2.example.com'', ''11211'');
149			END IF;
150			RETURN;
151			END;' LANGUAGE 'plpgsql';
152
153			-- The following function is an example of a trigger function that is
154			-- used to replace the value of something in the cache with its new
155			-- value.
156			CREATE OR REPLACE FUNCTION auth_passwd_trg_upd() RETURNS TRIGGER AS 'BEGIN
157			IF OLD.passwd != NEW.passwd THEN
158			PERFORM mc_init();
159			PERFORM memcache_replace(''user_id_'' \|\| NEW.user_id \|\| ''_password'', NEW.passwd);
160			END IF;
161			RETURN NEW;
162			END;' LANGUAGE 'plpgsql';
163
164			-- Activate the trigger for UPDATEs
165			CREATE TRIGGER auth_passwd_upd_trg
166			AFTER UPDATE ON passwd
167			FOR EACH ROW EXECUTE PROCEDURE auth_passwd_upd();
168
169
170			-- The above is not transaction safe, however. A better approach is
171			-- to have pgmemcache invalidate the cached data, but not replace it.
172			CREATE OR REPLACE FUNCTION auth_passwd_trg_upd() RETURNS TRIGGER AS 'BEGIN
173			IF OLD.passwd != NEW.passwd THEN
174			PERFORM mc_init();
175			PERFORM memcache_delete(''user_id_'' \|\| NEW.user_id \|\| ''_password'');
176			END IF;
177			RETURN NEW;
178			END;' LANGUAGE 'plpgsql';
179
180
181			-- Here's an example delete trigger
182			CREATE OR REPLACE FUNCTION auth_passwd_trg_del() RETURNS TRIGGER AS 'BEGIN
183			PERFORM mc_init();
184			PERFORM memcache_delete(''user_id_'' \|\| NEW.user_id \|\| ''_password'');
185			RETURN OLD;
186			END;' LANGUAGE 'plpgsql';
187
188			-- Activate the trigger for DELETEs
189			CREATE TRIGGER auth_passwd_del_trg
190			AFTER DELETE ON passwd
191			FOR EACH ROW EXECUTE PROCEDURE auth_passwd_del();
192
193
194			USAGE:
195
196			See the presentation at:
197
198			http://people.FreeBSD.org/~seanc/pgmemcache/pgmemcache.pdf
199
200			for additional instructions, examples (page 16-17), and ideas.
201
202
203			QUESTIONS/SUPPORT/BUGS:
204
205			Send email to sean@chittenden.org.