MySQL NDB Cluster API Developer Guide

6.5 Memcache protocol commands

The NDB engine supports the complete set of memcache protocol commands. When a newly installed server is started with the default server role and configuration schema, you should be able to run memcapable, a memcache-server verification tool, and see all tests pass. After a configuration has been customized, however—for instance, by disabling the FLUSH_ALL command—some memcapable tests are expected to fail.

GET, SET, ADD, REPLACE, and DELETE operations.  Each of these operations is always performed according to a cache policy associated with the memcache key prefix. It may operate on a locally cached item, an item stored in the database, or both. If an operation has been disabled for the prefix, the developer should be sure to test the disabled operation, since it may fail silently, or with a misleading response code.

CAS.  CAS, in the memcache protocol, refers to a compare and set value, which is used as a sort of version number on a cached value, and enables some optimistic application behavior

If a container includes a CAS column, the ndb engine will generate a unique CAS ID every time it writes a data value, and store it in the CAS column.

Some memcache operations include CAS checks, such as the ASCII CAS update which has the semantics update this value, but only if its CAS id matches the CAS id in the request. These operations are supported by the NDB engine. The check of the stored CAS ID against the application's CAS ID is performed in an atomic operation on the NDB data node. This allows CAS checks to work correctly even when multiple memcached servers access the same key-value pair.

If CAS ID checks are in use, and additional NDB Cluster APIs other than memcached are being used to manipulate the data, then the applications using those APIs are responsible for invalidating the stored CAS IDs whenever they update data. They can do this by setting the stored CAS ID value to 0 or NULL.

The CAS ID is generated using a scheme that attempts to prevent different servers from generating overlapping IDs. This scheme can be considered a best effort, but not a guarantee, of uniqueness. The scheme constructs an initial CAS as follows:

Part of the 32-bit Cluster GCI from the primary cluster at memcached startup time is used for the high-order bits of the 64-bit CAS ID

Part of the unique cluster node id in the primary cluster used when fetching configuration is used for middle-order bits of the CAS ID

An incrementing counter in the low-order bits of the CAS ID is at least 28-bits wide.

While the NDB engine generates one sequence of CAS IDs, the default engine—used for caching values in local memcached servers—generates a different sequence. Not all combinations of CAS behavior and cache policies have been tested, so any application developer wishing to use CAS should thoroughly test whether a particular configuration behaves as desired.

FLUSH_ALL.  FLUSH_ALL is implemented as follows: First, the NDB engine iterates over all configured key-prefixes. For any prefix whose cache policy enables a database flush (flush_from_db is true), it performs a scanning delete of every row in that prefix's container table. Other prefixes are ignored. This can be a slow operation if the table is large, and some memcache clients may time out before the DELETE operation is complete. After all database deletes are complete, the FLUSH_ALL command is forwarded to the standard caching engine, which sets a flag invalidating all cached data.

INCR and DECR.  All INCR and DECR operations are pushed down to the NDB data nodes and performed atomically there. This allows multiple memcached servers to increment or decrement the same key and be guaranteed a unique value each time.

The INCR and DECR operations have clearer and more useful semantics in the binary memcache protocol than in the ASCII protocol. The binary protocol is recommended.

The memcached ASCII protocol introduces some ambiguities in the handling of INCR and DECR, and forces the NDB engine to work in dup_numbers mode, in which the value_column and the math_column must mirror each other.

dup_numbers mode is enabled for key prefixes that meet all of the following conditions:

In dup_numbers mode, the following special behavior applies:

APPEND and PREPEND.  The memcache APPEND and PREPEND operations are implemented as a single transaction which involves a read of the existing value with an exclusive lock, followed by a write of the new value. The read and write are grouped atomically into a transaction, but unlike INCR and DECR, which can run natively on the data nodes, APPEND and PREPEND are executed inside the memcached server. This means that multiple memcached servers can contend to APPEND and PREPEND the same value, and that no updates will be lost, but this contention relies on locking behavior that could cause noticably increased latency.

STATS.  A memcached server can provide many sets of statistics; use STATS KEYWORD from a login shell.

All statistics usually available from the memcached 1.6 core and the default engine are available. For instance, STATS, STATS SLABS, and STATS SETTINGS are all currently supported as described in the memcached documentation. Some special sets of statistics are available from the NDB engine, using the STATS commands described in the following list: