119 lines
5.1 KiB
Plaintext
119 lines
5.1 KiB
Plaintext
-------------------------------------------------------------------------
|
|
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.
|