/memcached

Memcached protocol 'wrapper' for tarantool

Primary LanguageCBSD 2-Clause "Simplified" LicenseBSD-2-Clause

Static analysis Testing

memcached

Memcached protocol 'wrapper' for Tarantool.

Getting started

Prerequisites

  • Tarantol 1.6.8+ with header files (tarantool && tarantool-dev packages).
  • Cyrus SASL library (with header files)
  • Python >= 3.7 with next packages (for testing only):
    • PyYAML 5+
    • gevent 21+

Installation

Clone this repository and then build it using CMake:

git clone https://github.com/tarantool/memcached.git
cd memcached
git submodule update --init --recursive
cmake . -DCMAKE_BUILD_TYPE=RelWithDebugInfo -DCMAKE_INSTALL_PREFIX=/usr
make
make install

Or use LuaRocks (in this case you'll need libsmall, libsmall-dev, tarantool-dev packages available from our binary repository at http://tarantool.org/dist/master, and system package libsasl2-dev):

luarocks install https://raw.githubusercontent.com/tarantool/memcached/master/rockspecs/memcached-scm-1.rockspec --local

Usage

box.cfg{}
local memcached = require('memcached')
local instance = memcached.create('my_instance', '0.0.0.0:11211')

Now you're set up and ready to go!

How to connect

Install Tarantool package from repository (described here).

Paste the previous example to /etc/tarantool/instances.enabled/memcached.lua and start it with tarantoolctl start memcached.

Then try the following example:

$ printf "set key 0 60 5\r\nvalue\r\n" | nc localhost 11211
STORED
$ printf "get key\r\n" | nc localhost 11211
VALUE key 0 5
value
END
$ printf "set key2 0 60 6\r\nvalue2\r\n" | nc localhost 11211
STORED
$ printf "get key key2\r\n" | nc localhost 11211
VALUE key 0 5
value
VALUE key2 0 6
value2
END

API

  • local memcached = require('memcached') - acquire a library handle
  • local slab = memcached.slab.info() - show information about slab arena and quota.
  • local instance = memcached.create(<name>, <uri>, <opts>) - create a new instance, register it and run
    • name - a string with instance name
    • uri - a string with uri to bind to, for example: 0.0.0.0:11211 (only TCP is supported now)
    • opts - a table with options, the list of possible options is described in the configuration section
  • local instance = instance:cfg(<opts>) - (re)configure an existing instance. opts - a table with options, same as in create
  • local instance = instance:start() - start an instance
  • local instance = instance:stop() - stop an instance
  • local instance = instance:info() - return execution statistics

Configuration

  • readahead - (default) size of readahead buffer for connection. default is box->cfg->readahead
  • expire_enabled - availability of expiration daemon. default is true.
  • expire_items_per_iter - scan count for expiration (tuples processed in one transaction). default is 200.
  • expire_full_scan_time - time required for a full index scan (in seconds). default is 3600
  • verbosity - verbosity of memcached logging. default is 0.
  • flush_enabled - flush command availability. default is true
  • protocol - the protocol, one of negotiation, binary or text.
    • negotiation - detect the protocol automatically at handshake (the default)
    • binary - binary memcached protocol
    • text - text memcached protocol
  • engine - the engine to store data in
    • memory - store everything in memory. (using memtx engine)
    • disk - store everything on hdd/ssd (using vinyl engine) (not yet supported)
  • space_name - custom name for a memcached space, default is __mc_<instance name>
  • if_not_exists - do not throw error if an instance already exists.
  • sasl - enable or disable SASL support (disabled by default)

SASL support

Usual rules for memcached are applicable for this plugin:

  1. Create user (NOTE: it'll use custom folder):

    echo testpass | saslpasswd2 -p -c testuser -f /tmp/test-tarantool-memcached.sasldb
  2. Place configuration file /etc/sasl2/tarantool-memcached.conf. For example:

    mech_list: plain cram-md5
    log_level: 7
    sasldb_path: /tmp/test-tarantool-memcached.sasldb
    

    NOTE: This will disable 'ANONYMOUS' (and other, that aren't listed) authentication plugins.

    NOTE: This will set logging level to the highest possible

    NOTE: This will set custom path for database path

  3. Run Tarantool with memcached plugin with SASL enabled

    local memcached = require('memcached')
    local instance = memcached.create('my_instance', '0.0.0.0:11211', {
      sasl = true
    })
  4. Use your favorite binary(!!) memcached client, that supports(!!) SASL:

    Example using Python's 'python-binary-memcached' library

    import bmemcached
    client = bmemcached.Client(('127.0.0.1:11211', ), 'testuser', 'testpasswd')
    client.set('key', 'value')
    print(client.get('key'))
    

For custom configuration file path, please, use SASL_CONF_PATH environment variable.

What's supported, what's not and other features

Everything is supported, unless the opposite is stated explicitly

  • Text protocol commands:
    • set/add/cas/replace/append/prepend commands (set section)
    • get/gets commands (including multiget)
    • delete command
    • incr/decr commands
    • flush/version/quit commands
    • verbosity - partially, logging is not very good.
    • stat - reset is supported and all stats too.
  • Binary protocol's commands:
    • get/getk/getq/getkq commands (get section)
    • add/addq/replace/replaceq/set/setq commands (set section)
    • quit/quitq/flush/flushq/noop/version commands
    • gat/gatq/touch/gatk/gatkq commands
    • append/prepend/incr/decr
    • verbosity - partially, logging is not very good.
    • stat - reset is supported and all stats too.
    • SASL authentication is supported
    • range operations are not supported as well.
  • Expiration is supported
  • Flush is supported
  • The protocol is synchronous
  • Full support of Tarantool means of consistency (write-ahead logs, snapshots, replication)
  • You can access data from Lua
  • for now LRU is not supported
  • TAP is not supported (for now)
  • VBucket is not supported (for now)
  • UDP/UNIX sockets are not supported (for now)

Caution

This rock is in early beta.

Hacking

We're collecting information for the module developers in the HACKING.md file.