README
1-------------------------------------------------------------------------
2The Memcache API for MySQL Cluster 7.2
3-------------------------------------------------------------------------
4
5
6Memcached is a high-performance data cache. Memcached servers are often
7expected to serve 100,000 operations per second or more.
8
9The API is based on Memcached 1.6 from http://www.memcached.org/.
10It is designed to do everything memcached does, with similar performance,
11and automatically persist data to MySQL Cluster.
12
13The Memcache API is highly configurable. Multiple memcached servers can connect
14to multiple clusters and access data from many different tables. It supports a
15large number of cache policies, based on the prefix of a memcache key. Some
16keys can be stored in local cache only, while other keys are written though
17synchronously to the database but stored in cacne, and still other keys go
18directly to the database without using a local cache at all.
19
20In the default configuration, all values will be persistently stored in
21MySQL Cluster, except keys that begin with "mc:" or "t:" which are treated
22specially.
23
24-------------------------------------------------------------------------
25QUICK START
26-------------------------------------------------------------------------
27
28STARTING THE SERVER
29-------------------
30To create a simple sandbox to demonstrate MySQL Cluster with memcache,
31run "sandbox.sh start", then continue reading.
32
33Alternately, if you have a running cluster (with room to add a new API node)
34and want to add a memcache server to it, there are two steps.
35 (1) Create the "ndbmemcache" configuration database
36 # mysql -u root < ndb_memcache_metadata.sql
37 (2) Start a memcached server
38 # ../bin/memcached -E ../lib/ndb_engine.so
39
40It is not possible to start a memcached server until the configuration tables
41have been created.
42
43
44TESTING
45-------
46Once the server is running, if you have installed the libmemcached clients
47(from http://libmemcached.org), you should be able to run "memcapable" and
48see all tests pass.
49
50You can also test the installation using mysql-test-run. From the mysql-test
51directory, run "mysql-test-run.pl --suite=ndb_memcache". This is a preview
52release, so test failures are still expected on some platforms.
53
54If you see a test failure some other problem, please report it on the "Cluster"
55forum at http://forums.mysql.com/
56
57
58RUN SOME CLIENT COMMANDS
59--------------------------
60From another window, you can run any sort of memcached client using either the
61text protocol or the binary protocol -- including plain "telnet".
62
63$ telnet localhost 11211
64Escape character is '^]'.
65set key1 0 0 4
66abcd
67
68get key1
69
70delete key1
71
72
73-------------------------------------------------------------------------
74UPGRADING THE CONFIGURATION SCHEMA FROM EARLIER PRE-RELEASE VERSIONS
75-------------------------------------------------------------------------
76The current version of the configuration schema and demonstration tables
77is 1.2. The SQL script "update_to_1.2.sql" is available and can be used
78to update version 1.1 configuration and demo tables to version 1.2.
79
80
81-------------------------------------------------------------------------
82THE DEFAULT SERVER ROLE
83-------------------------------------------------------------------------
84
85In the default configuration, all keys except those beginning with "mc:", "t:"
86or "b:" are stored in the table called "demo_table" in the ndbmemcache schema.
87In this table, memcache keys are stored in the 250-byte VARCHAR column called
88mkey, and memcache values are stored in the VARBINARY(13500) column called
89string_value. Values larger than 13,500 bytes cannot be stored in this table.
90
91Keys beginning with "b:" allow storage of large values. For this prefix,
92a main table row is stored in the demo_table_large table, and large values
93are partitioned into stripes in the table called external_values. The size
94limit on large objects depends on the stripe size of the parts table; in
95the demonstration schema, the size limit is approximately 3.5 MB. However,
96memcached itself also imposes a size limit values, which by default is 1 MB.
97
98Keys beginning with "mc:" are stored only in local cache (their cache policy
99is "mc-only").
100
101Keys beginning with "t:" demonstrate some other features of the memcached
102server, including:
103 * using tab-separated values to store data in multiple columns.
104 * automatically expiring stored data based on stored expiration times
105 * storing of memcached flags in the database
106These values are stored in "demo_table_tabs". Note that the key to this table
107is an integer, so valid memcache keys are "t:1", "t:2", etc.
108
109
110-------------------------------------------------------------------------
111LIMITATIONS
112-------------------------------------------------------------------------
113
114"SET" and "ENUM" columns rely on metadata which is only properly available to
115the MySQL server. While they may work in some situations, they are not
116fully supported. Bitfields are not supported at all. TEXT and BLOB columns
117are also not supported, though BLOB-like large values can be stored in an
118external values table, as described above.
119