Skip navigation links
4.3.8 memcached Protocol »
Section Navigation      [Toggle]

4.3.7. Using the MySQL memcached UDFs

The memcached MySQL User Defined Functions (UDFs) enable you to set and retrieve objects from within MySQL 5.0 or greater.

To install the MySQL memcached UDFs, download the UDF package from http://tangent.org/586/Memcached_Functions_for_MySQL.html. You will need to unpack the package and run configure to configure the build process. When running configure, use the --with-mysql option and specify the location of the mysql_config command. Note that you must be running : 

shell> tar zxf memcached_functions_mysql-0.5.tar.gz
shell> cd memcached_functions_mysql-0.5
shell> ./configure --with-mysql-config=/usr/local/mysql/bin/mysql_config

Now build and install the functions: 

shell> make
shell> make install

You may want to copy the MySQL memcached UDFs into your MySQL plugins directory: 

shell> cp /usr/local/lib/libmemcached_functions_mysql* /usr/local/mysql/lib/mysql/plugins/

Once installed, you must initialize the function within MySQL using CREATE and specifying the return value and library. For example, to add the memc_get() function: 

mysql> CREATE FUNCTION memc_get RETURNS STRING SONAME "libmemcached_functions_mysql.so";

You must repeat this process for each function that you want to provide access to within MySQL. Once you have created the association, the information will be retained, even over restarts of the MySQL server. You can simplify the process by using the SQL script provided in the memcached UDFs package: 

shell> mysql <sql/install_functions.sql

Alternatively, if you have Perl installed, then you can use the supplied Perl script, which will check for the existence of each function and create the function/library association if it has not already been defined: 

shell> utils/install.pl --silent

The --silent option installs everything automatically. Without this option, the script will ask whether you want to install each of the available functions.

The interface remains consistent with the other APIs and interfaces. To set up a list of servers, use the memc_servers_set() function, which accepts a single string containing and comma-separated list of servers: 

mysql> SELECT memc_servers_set('192.168.0.1:11211,192.168.0.2:11211');

Note

The list of servers used by the memcached UDFs is not persistent over restarts of the MySQL server. If the MySQL server fails, then you must re-set the list of memcached servers.

To set a value, use memc_set: 

mysql> SELECT memc_set('myid', 'myvalue');

To retrieve a stored value: 

mysql> SELECT memc_get('myid');

The list of functions supported by the UDFs, in relation to the standard protocol functions, is shown in the following table.

MySQL memcached UDF Function Equivalent to
memc_get() Generic get()
memc_get_by_key(master_key, key, value) Like the generic get(), but uses the supplied master key to select the server to use.
memc_set() Generic set()
memc_set_by_key(master_key, key, value) Like the generic set(), but uses the supplied master key to select the server to use.
memc_add() Generic add()
memc_add_by_key(master_key, key, value) Like the generic add(), but uses the supplied master key to select the server to use.
memc_replace() Generic replace()
memc_replace_by_key(master_key, key, value) Like the generic replace(), but uses the supplied master key to select the server to use.
memc_prepend(key, value) Prepend the specified value to the current value of the specified key.
memc_prepend_by_key(master_key, key, value) Prepend the specified value to the current value of the specified key, but uses the supplied master key to select the server to use.
memc_append(key, value) Append the specified value to the current value of the specified key.
memc_append_by_key(master_key, key, value) Append the specified value to the current value of the specified key, but uses the supplied master key to select the server to use.
memc_delete() Generic delete()
memc_delete_by_key(master_key, key, value) Like the generic delete(), but uses the supplied master key to select the server to use.
memc_increment() Generic incr()
memc_decrement() Generic decr()

The respective *_by_key() functions are useful when you want to store a specific value into a specific memcached server, possibly based on a differently calculated or constructed key.

The memcached UDFs include some additional functions:

  • memc_server_count()

    Returns a count of the number of servers in the list of registered servers.

  • memc_servers_set_behavior(behavior_type, value), memc_set_behavior(behavior_type, value)

    Set behaviors for the list of servers. These behaviors are identical to those provided by the libmemcached library. For more information on libmemcached behaviors, see Section 4.3.1, “Using libmemcached”.

    You can use the behavior name as the behavior_type: 

    mysql> SELECT memc_servers_behavior_set("MEMCACHED_BEHAVIOR_KETAMA",1);

  • memc_servers_behavior_get(behavior_type), memc_get_behavior(behavior_type, value)

    Returns the value for a given behavior.

  • memc_list_behaviors()

    Returns a list of the known behaviors.

  • memc_list_hash_types()

    Returns a list of the supported key-hashing algorithms.

  • memc_list_distribution_types()

    Returns a list of the supported distribution types to be used when selecting a server to use when storing a particular key.

  • memc_libmemcached_version()

    Returns the version of the libmemcached library.

  • memc_stats()

    Returns the general statistics information from the server.