/[pgmemcache]/trunk/README.pgmemcache
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /trunk/README.pgmemcache

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3 - (show annotations)
Thu Jul 20 09:57:48 2006 UTC (17 years, 8 months ago) by dpavlin
File size: 7095 byte(s)
make working branch
1 # $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.

  ViewVC Help
Powered by ViewVC 1.1.26