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:

• The container includes a math column, AND

• The container includes a single value column, AND

• The data type of the value column is non-numeric

In dup_numbers mode, the following special behavior applies:

• Whenever an ASCII SET, ADD, or REPLACE command sets a value that could be interpreted as numeric, and the container defines a math_column, then the text value is stored in the value column and the numeric value is also stored in the math column.

• Whenever an ASCII INCR or DECR command is performed, the text value in that container's value column is set to NULL.

• Whenever a memcached GET command is issued, and the container's value column is NULL, but the container's math column is not NULL, then the math value is returned to the client.

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:

• STATS NDB: Returns NDB API statistics for each NDB cluster connection. These are the same internal statistics which are available as system status variables from the MySQL Server. See NDB API Statistics Counters and Variables, for more information.

• STATS SCHEDULER: Returns statistics for the S scheduler. All of these statistics are reported on the cluster connection level.

  • cl%d.conn%d.sent_operations: Records the number of operations sent from the connection's send thread to the cluster data nodes.

  • cl%d.conn%d.batches: Records the number of operation batches sent from the send thread to the data nodes. Each batch contains one or more operations. sent_operations / batches can be used to compute the average batch size.

  • cl%d.conn%d.timeout_races: This records a rare race condition that may occur in the send thread. It is expected to be 0, or to be a very low number compared to sent_operations.

• stats reconf: If the NDB engine is currently loading a new configuration, command returns the single-line message Loading revno, where revno is the version number of the configuration being loaded.

  Otherwise, this command returns the statistical message Running revno.

  revno starts at 1 when the memcached server begins running, and is incremented by 1 for each online reconfiguration.