MySQL 5.6 Reference Manual Including MySQL NDB Cluster 7.3-7.4 Reference Guide

16.2.3.9 Using the memcached TCP Text Protocol

Communicating with a memcached server can be achieved through either the TCP or UDP protocols. When using the TCP protocol, you can use a simple text based interface for the exchange of information.

When communicating with memcached, you can connect to the server using the port configured for the server. You can open a connection with the server without requiring authorization or login. As soon as you have connected, you can start to send commands to the server. When you have finished, you can terminate the connection without sending any specific disconnection command. Clients are encouraged to keep their connections open to decrease latency and improve performance.

Data is sent to the memcached server in two forms:

Both text lines (commands and responses) and unstructured data are always terminated with the string \r\n. Because the data being stored may contain this sequence, the length of the data (returned by the client before the unstructured data is transmitted should be used to determine the end of the data.

Commands to the server are structured according to their operation:

For reference, a list of the different commands supported and their formats is provided below.

Table 16.2 memcached Command Reference

Command Command Formats
set set key flags exptime length, set key flags exptime length noreply
add add key flags exptime length, add key flags exptime length noreply
replace replace key flags exptime length, replace key flags exptime length noreply
append append key length, append key length noreply
prepend prepend key length, prepend key length noreply
cas cas key flags exptime length casunique, cas key flags exptime length casunique noreply
get get key1 [key2 ... keyn]
gets
delete delete key, delete key noreply, delete key expiry, delete key expiry noreply
incr incr key, incr key noreply, incr key value, incr key value noreply
decr decr key, decr key noreply, decr key value, decr key value noreply
stat stat, stat name, stat name value

When sending a command to the server, the response from the server is one of the settings in the following table. All response values from the server are terminated by \r\n:

Table 16.3 memcached Protocol Responses

String Description
STORED Value has successfully been stored.
NOT_STORED The value was not stored, but not because of an error. For commands where you are adding a or updating a value if it exists (such as add and replace), or where the item has already been set to be deleted.
EXISTS When using a cas command, the item you are trying to store already exists and has been modified since you last checked it.
NOT_FOUND The item you are trying to store, update or delete does not exist or has already been deleted.
ERROR You submitted a nonexistent command name.
CLIENT_ERROR errorstring There was an error in the input line, the detail is contained in errorstring.
SERVER_ERROR errorstring There was an error in the server that prevents it from returning the information. In extreme conditions, the server may disconnect the client after this error occurs.
VALUE keys flags length The requested key has been found, and the stored key, flags and data block are returned, of the specified length.
DELETED The requested key was deleted from the server.
STAT name value A line of statistics data.
END The end of the statistics data.