-------------------------------------------------------------------------
The Memcache API for MySQL Cluster 7.2
-------------------------------------------------------------------------


Memcached is a high-performance data cache.  Memcached servers are often 
expected to serve 100,000 operations per second or more.  

The API is based on Memcached 1.6 from http://www.memcached.org/.
It is designed to do everything memcached does, with similar performance, 
and automatically persist data to MySQL Cluster.  

The Memcache API is highly configurable. Multiple memcached servers can connect 
to multiple clusters and access data from many different tables.  It supports a 
large number of cache policies, based on the prefix of a memcache key.  Some 
keys can be stored in local cache only, while other keys are written though 
synchronously to the database but stored in cacne, and still other keys go 
directly to the database without using a local cache at all.

In the default configuration, all values will be persistently stored in 
MySQL Cluster, except keys that begin with "mc:" or "t:" which are treated
specially.

-------------------------------------------------------------------------
QUICK START
-------------------------------------------------------------------------

STARTING THE SERVER
-------------------
To create a simple sandbox to demonstrate MySQL Cluster with memcache, 
run "sandbox.sh start", then continue reading.

Alternately, if you have a running cluster (with room to add a new API node)
and want to add a memcache server to it, there are two steps.
 (1) Create the "ndbmemcache" configuration database
     # mysql -u root < ndb_memcache_metadata.sql
 (2) Start a memcached server
     # ../bin/memcached -E ../lib/ndb_engine.so 

It is not possible to start a memcached server until the configuration tables
have been created.


TESTING
-------
Once the server is running, if you have installed the libmemcached clients 
(from http://libmemcached.org), you should be able to run "memcapable" and 
see all tests pass.

You can also test the installation using mysql-test-run.  From the mysql-test
directory, run "mysql-test-run.pl --suite=ndb_memcache".  This is a preview 
release, so test failures are still expected on some platforms.  

If you see a test failure some other problem, please report it on the "Cluster" 
forum at http://forums.mysql.com/


RUN SOME CLIENT COMMANDS 
--------------------------
From another window, you can run any sort of memcached client using either the 
text protocol or the binary protocol -- including plain "telnet".  

$ telnet localhost 11211
Escape character is '^]'.
set key1 0 0 4
abcd

get key1

delete key1


-------------------------------------------------------------------------
UPGRADING THE CONFIGURATION SCHEMA FROM EARLIER PRE-RELEASE VERSIONS
-------------------------------------------------------------------------
The current version of the configuration schema and demonstration tables 
is 1.2. The SQL script "update_to_1.2.sql" is available and can be used 
to update version 1.1 configuration and demo tables to version 1.2.


-------------------------------------------------------------------------
THE DEFAULT SERVER ROLE
-------------------------------------------------------------------------

In the default configuration, all keys except those beginning with "mc:", "t:" 
or "b:" are stored in the table called "demo_table" in the ndbmemcache schema.
In this table, memcache keys are stored in the 250-byte VARCHAR column called
mkey, and memcache values are stored in the VARBINARY(13500) column called
string_value.  Values larger than 13,500 bytes cannot be stored in this table.

Keys beginning with "b:" allow storage of large values.  For this prefix, 
a main table row is stored in the demo_table_large table, and large values 
are partitioned into stripes in the table called external_values.  The size 
limit on large objects depends on the stripe size of the parts table; in
the demonstration schema, the size limit is approximately 3.5 MB.  However, 
memcached itself also imposes a size limit values, which by default is 1 MB.

Keys beginning with "mc:" are stored only in local cache (their cache policy
is "mc-only").

Keys beginning with "t:" demonstrate some other features of the memcached 
server, including: 
  * using tab-separated values to store data in multiple columns.
  * automatically expiring stored data based on stored expiration times
  * storing of memcached flags in the database
These values are stored in "demo_table_tabs".  Note that the key to this table
is an integer, so valid memcache keys are "t:1", "t:2", etc.


-------------------------------------------------------------------------
LIMITATIONS
-------------------------------------------------------------------------

"SET" and "ENUM" columns rely on metadata which is only properly available to
the MySQL server.  While they may work in some situations, they are not 
fully supported.  Bitfields are not supported at all.  TEXT and BLOB columns 
are also not supported, though BLOB-like large values can be stored in an 
external values table, as described above.