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. |