Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tarantool/memcached

Memcached protocol 'wrapper' for tarantool
https://github.com/tarantool/memcached

memchached tarantool

Last synced: 27 days ago
JSON representation

Memcached protocol 'wrapper' for tarantool

Awesome Lists containing this project

README

        



[![Static analysis](https://github.com/tarantool/memcached/actions/workflows/check.yaml/badge.svg)](https://github.com/tarantool/memcached/actions/workflows/check.yaml)
[![Testing](https://github.com/tarantool/memcached/actions/workflows/testing.yaml/badge.svg)](https://github.com/tarantool/memcached/actions/workflows/testing.yaml)

# 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:

``` bash
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`):

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

### Usage

``` bash
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](https://www.tarantool.io/download/)).

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

Then try the following example:

``` bash
$ 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(, , )` - 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()` - (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_`
* *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):

``` bash
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

```lua
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](https://github.com/jaysonsantos/python-binary-memcached)
```
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](HACKING.md) file.