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:
Text lines, which are used to send commands to the server, and receive responses from the server.
Unstructured data, which is used to receive or send the value information for a given key. Data is returned to the client in exactly the format it was provided.
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:
Storage commands:
set
, add
,
replace
, append
,
prepend
, cas
Storage commands to the server take the form:
command key [flags] [exptime] length [noreply]
Or when using compare and swap (cas):
cas key [flags] [exptime] length [casunique] [noreply]
Where:
command
— the command name.
set
— Store value against
key
add
— Store this value
against key if the key does not already exist
replace
— Store this
value against key if the key already exists
append
— Append the
supplied value to the end of the value for the
specified key. The flags
and
exptime
arguments should not be
used.
prepend
— Append value
currently in the cache to the end of the supplied
value for the specified key. The
flags
and
exptime
arguments should not be
used.
cas
— Set the specified
key to the supplied value, only if the supplied
casunique
matches. This is
effectively the equivalent of change the
information if nobody has updated it since I last
fetched it.
key
— the key. All data is
stored using a the specific key. The key cannot
contain control characters or whitespace, and can be
up to 250 characters in size.
flags
— the flags for the
operation (as an integer). Flags in
memcached are transparent. The
memcached server ignores the
contents of the flags. They can be used by the client
to indicate any type of information. In
memcached 1.2.0 and lower the value
is a 16-bit integer value. In
memcached 1.2.1 and higher the
value is a 32-bit integer.
exptime
— the expiry time, or
zero for no expiry.
length
— the length of the
supplied value block in bytes, excluding the
terminating \r\n
characters.
casunique
— is a unique
64-bit value of an existing entry. This will be used
to compare against the existing value. You should use
the value returned by the gets
command when issuing cas
updates.
noreply
— tells the server
not to reply to the command.
For example, to store the value abcdef
into the key xyzkey
, you would use:
set xyzkey 0 0 6\r\nabcdef\r\n
The return value from the server will be one line, specifying the status or error information. For more information, see Table 14.2, “memcached Protocol Responses”.
Retrieval commands:
get
, gets
Retrieval commands take the form:
get key1 [key2 .... keyn] gets key1 [key2 ... keyn]
You can supply multiple keys to the commands, with each requested key separated by whitespace.
The server will respond with an information line of the form:
VALUE key flags bytes [casunique]
Where:
key
— the key name.
flags
— the value of the flag
integer supplied to the memcached
server when the value was stored.
bytes
— the size (excluding
the terminating \r\n
character
sequence) of the stored value.
casunique
— the unique 64-bit
integer that identifies the item.
The information line will immediately be followed by the value data block. For example:
get xyzkey\r\n VALUE xyzkey 0 6\r\n abcdef\r\n
If you have requested multiple keys, an information line and data block will be returned for each key found. If a requested key does not exist in the cache, no information is returned.
Delete commands:
delete
Deletion commands take the form:
delete key [time] [noreply]
Where:
key
— the key name.
time
— the time in seconds
(or a specific Unix time) for which the client wishes
the server to refuse add
or
replace
commands on this key. All
add
, replace
,
get
, and gets
commands will fail during this period.
set
operations will succeed. After
this period, the key will be deleted permanently and
all commands will be accepted.
If not supplied, the value is assumed to be zero (delete immediately).
noreply
— tells the server
not to reply to the command.
Responses to the command will either be
DELETED
to indicate that the key was
successfully removed, or NOT_FOUND
to
indicate that the specified key could not be found.
Increment/Decrement:
incr
, decr
The increment and decrement commands change the value of a key within the server without performing a separate get/set sequence. The operations assume that the currently stored value is a 64-bit integer. If the stored value is not a 64-bit integer, then the value is assumed to be zero before the increment or decrement operation is applied.
Increment and decrement commands take the form:
incr key value [noreply] decr key value [noreply]
Where:
key
— the key name.
value
— an integer to be used
as the increment or decrement value.
noreply
— tells the server
not to reply to the command.
The response will be:
NOT_FOUND
— the specified key
could not be located.
value
— the new value of the
specified key.
Values are assumed to be unsigned. For
decr
operations the value will never be
decremented below 0. For incr
operations, the value will be wrap around the 64-bit
maximum.
Statistics commands:
stats
The stats
command provides detailed
statistical information about the current status of the
memcached instance and the data it is
storing.
Statistics commands take the form:
STAT [name] [value]
Where:
name
— is the optional name
of the statistics to return. If not specified, the
general statistics are returned.
value
— a specific value to
be used when performing certain statistics operations.
The return value is a list of statistics data, formatted as follows:
STAT name value
The statistics are terminated with a single line,
END
.
For more information, see Section 14.5.4, “Getting memcached Statistics”.
For reference, a list of the different commands supported and their formats is provided below.
Table 14.1. 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 expory 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 will be one of the settings in the following table. All
response values from the server are terminated by
\r\n
:
Table 14.2. 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 will be
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. |
User Comments
Add your own comment.