Tarantool User Guide, version 1.5.2-20-g5f5d924

Tarantool is an in-memory NoSQL database management system. The code is available for free under the terms of the BSD license. Supported platforms are GNU/Linux, Mac OS and FreeBSD.

The server maintains all its data in random-access memory, and therefore has very low read latency. The server keeps persistent copies of the data in non-volatile storage, such as disk, when users request "snapshots". The server maintains a write-ahead log (WAL) to ensure consistency and crash safety of the persistent copies. The server performs inserts and updates atomically -- changes are not considered complete until the WAL is written. The logging subsystem supports group commit.

When the rate of data changes is high, the write-ahead log file (or files) can grow quickly. This uses up disk space, and increases the time necessary to restart the server (because the server must start with the last snapshot, and then replay the transactions that are in the log). The solution is to make snapshots frequently. Therefore the server ensures that snapshots are quick, resource-savvy, and non-blocking . To accomplish this, the server uses delayed garbage collection for data pages and uses a copy-on-write technique for index pages. This ensures that the snapshot process has a consistent read view.

Tarantool is lock-free. Instead of the operating system's concurrency primitives, such as mutexes, Tarantool uses cooperative multitasking to handle thousands of connections simultaneously. There is a fixed number of independent execution threads. The threads do not share state. Instead they exchange data using low-overhead message queues. While this approach limits the number of cores that the server will use, it removes competition for the memory bus and ensures peak scalability of memory access and network throughput. CPU utilization of a typical highly-loaded Tarantool server is under 10%.

Unlike most NoSQL DBMSs, Tarantool supports secondary index keys and multi-part index keys as well as primary keys. The possible index types are HASH, TREE, and BITSET.

As its key feature, Tarantool supports Lua stored procedures, which can access and modify data atomically. Users can create, modify and drop Lua procedures at runtime.

There is a role not only for Lua procedures, but also for Lua programs. During startup, Lua programs can be used to define triggers and background tasks, or interact with networked peers. Unlike popular application development frameworks based on a "reactor" pattern, networking in server-side Lua is sequential, yet very efficient, as it is built on top of the cooperative multitasking environment that Tarantool itself uses.

Extended with Lua, Tarantool typically replaces multiple components of an existing system. Complex multi-tier Web application architectures become simpler, and performance is good.

Tarantool supports asynchronous replication , locally or to a remote host. Replication does not cause blocking of writes to the master database. If the master becomes unavailable, a replica can assume the master role without requiring a restart.

Tarantool is in production today. Tarantool was created by and is actively used at Mail.Ru, one of the leading Russian web content providers. At Mail.Ru the software serves the “hottest” data, such as online users and their sessions, online application properties, mapping between users and their serving shards, and so on.

Outside Mail.Ru the software is used by a growing number of projects in online gaming, digital marketing, and social media industries. While product development is sponsored by Mail.Ru, the roadmap, the bugs database and the development process are fully open. The software incorporates patches from dozens of community contributors. The Tarantool community writes and maintains most of the drivers for programming languages.

This manual is written in DocBook 5 XML markup language and is using the standard DocBook XSL formatting conventions:

UNIX shell command input is prefixed with '$ ' and is in a fixed-width font:

$ tarantool_box --background

File names are also in a fixed-width font:

/path/to/var/dir

Text that represents user input is in boldface:

$ your input here

Within user input, replaceable items are in italics:

$ tarantool_box --option

Please report bugs in Tarantool at http://github.com/tarantool/tarantool/issues. You can contact developers directly on #tarantool IRC channel or via a mailing list, Tarantool Google group.

The repositories for the “stable” release are at tarantool.org/dist. The repositories for the “master” release are at tarantool.org/dist/master. Since this is the manual for the “stable” release, all instructions use tarantool.org/dist.

An automatic build system creates, tests and publishes packages for every push into the stable branch. Therefore if you looked at tarantool.org/dist you would see many files. Names of binary packages have the format tarantool-<version>-<OS>-<machine>.tar.gz. Here is one example:

tarantool-1.5.1-97-g8e8cd06-linux-x86_64.tar.gz    26-Sep-2013 15:55             3664777

which means “Tarantool package, major version = 1, minor version number = 5, patch number 1, git revision id g8e8cd06, is a Linux x86 64-bit compressed tarball, pushed on September 26 2013, which contains 3.6 MB.”

To download and install the package that's appropriate for your environment, start a shell (terminal) and enter one of the following sets of command-line instructions.

# DEBIAN commands for Tarantool stable binary download:
# There is always an up-to-date Debian repository at http://tarantool.org/dist/debian
# The repository contains builds for Debian unstable "Sid", stable "Wheezy", forthcoming "Jessie", ...
# add the tarantool.org repository to your apt sources list:
# ($release is an environment variable which will contain the Debian version code e.g. "Wheezy")
wget http://tarantool.org/dist/public.key
sudo apt-key add ./public.key
release=`lsb_release -c -s`
# append two lines to a list of source repositories
echo "deb http://tarantool.org/dist/debian/ $release main" | sudo tee -a /etc/apt/sources.list.d/tarantool.list
echo "deb-src http://tarantool.org/dist/debian/ $release main" | sudo tee -a /etc/apt/sources.list.d/tarantool.list
# install
sudo apt-get update
sudo apt-get install tarantool tarantool-client

# UBUNTU commands for Tarantool stable binary download:
# There is always an up-to-date Ubuntu repository at http://tarantool.org/dist/ubuntu
# The repository contains builds for Ubuntu 12.04 "precise", 12.10 "quantal", 13.04 "raring", 13.10 "saucy", ...
# add the tarantool.org repository to your apt sources list:
# ($release is an environment variable which will contain the Ubuntu version code e.g. "precise")
# (if you want the version that comes with Ubuntu, start with the lines that follow the '# install' comment)
cd ~
wget http://tarantool.org/dist/public.key
sudo apt-key add ./public.key
release=`lsb_release -c -s`
# append two lines to a list of source repositories
echo "deb http://tarantool.org/dist/ubuntu/ $release main" | sudo tee -a /etc/apt/sources.list.d/tarantool.list
echo "deb-src http://tarantool.org/dist/ubuntu/ $release main" | sudo tee -a /etc/apt/sources.list.d/tarantool.list
# install
sudo apt-get update
sudo apt-get install tarantool tarantool-client

# CENTOS commands for Tarantool stable binary download:
# These instructions are applicable for CentOS version 5 or 6, and RHEL version 5 or 6
# Pick the CentOS repository which fits your CentOS/RHEL version and your x86 platform:
# http://tarantool.org/dist/centos/5/os/i386 for version 5, x86-32
# http://tarantool.org/dist/centos/5/os/x86_64 for version 5, x86-64
# http://tarantool.org/dist/centos/6/os/i386 for version 6, x86-32
# http://tarantool.org/dist/centos/6/os/x86_64 for version 6, x86-64
# Add the following section to your yum repository list (/etc/yum.repos.d/tarantool.repo):
# (in the following instructions, $releasever i.e. CentOS release version must be either 5 or 6)
# (in the following instructions, $basearch i.e. base architecture must be either i386 or x86_64)
# [tarantool]
# name=CentOS-$releasever - Tarantool
# baseurl=http://tarantool.org/dist/centos/$releasever/os/$basearch/
# enabled=1
# gpgcheck=0
# For example, if you have CentOS version 6 and x86-64, you can
# add the new section thus:
echo "[tarantool]" | sudo tee /etc/yum.repos.d/tarantool.repo
echo "name=CentOS-6 - Tarantool"| sudo tee -a /etc/yum.repos.d/tarantool.repo
echo "baseurl=http://tarantool.org/dist/centos/6/os/x86_64/" | sudo tee -a /etc/yum.repos.d/tarantool.repo
echo "enabled=1" | sudo tee -a /etc/yum.repos.d/tarantool.repo
echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/tarantool.repo

# GENTOO commands for Tarantool stable binary download:
# Tarantool is available from tarantool portage overlay. Use layman to add the overlay to your system:
layman -S
layman -a tarantool
emerge dev-db/tarantool -av

# ANY-LINUX commands for Tarantool stable binary download:
# If you have a GNU/Linux distribution which is not one of the above,
# or if you want to install on your own subdirectory without affecting /usr /etc etc.,
# start your browser and go to
# http://tarantool.org/download.html download page.
# Look for words similar to "Other Linux distributions". You will want the
# binary tarball (.tar.gz) file for your release architecture (32-bit or 64-bit).
# Click on either "32-bit" or "64-bit" depending on your release architecture.
# This will cause a download of the latest stable tarball.
# Suppose it is tarantool-1.5.1-133-g11edda1-linux-x86_64.tar.gz. Say:
tar zxvf tarantool-1.5.1-133-g11edda1-linux-x86_64.tar.gz
# You now have a directory named tarantool-1.5.1-133-g11edda1-linux-x86_64.
# Let's move it to ~/tarantool, which is an easier name to remember.
mv tarantool-1.5.1-133-g11edda1-linux-x86_64 ~/tarantool
# Within it there is a subdirectory /bin containing both server and client.

# FREEBSD commands for Tarantool stable binary download:
# With your browser go to the FreeBSD ports page
# http://www.freebsd.org/ports/index.html
# Enter the search term: tarantool
# Choose the package you want ...
# However, there is a known issue with the binary of Tarantool
# version 1.5, see # https://github.com/tarantool/tarantool/issues/19.

# MAC OS X commands for Tarantool stable binary download:
# This is actually a “homebrew” recipe
# so it's not a true binary download, some source code is involved.
# First upgrade Clang (the C compiler) to version 3.2 or later using
# Command Line Tools for Xcode disk image version 4.6+ from Apple Developer web-site.
brew install --use-clang http://tarantool.org/dist/tarantool.rb
# or
brew install http://tarantool.org/dist/tarantool.rb

More advice for binary downloads is at http://tarantool.org/download.html.

For downloading Tarantool source and building it, the platforms can differ and the preferences can differ. But the steps are always the same. Here in the manual we'll explain what the steps are, then on the Internet you can look at some example scripts.

1. Get tools and libraries that will be necessary for building and testing. The absolutely necessary ones are:

Here are names of tools and libraries which may have to be installed in advance, using “sudo apt-get” (for Ubuntu), “sudo yum install” (for CentOS), or the equivalent on other platforms. Different platforms may use slightly different names. Do not worry about the “optional, for build with -DENABLE_DOC” ones unless you intend to work on the documentation.

   binutils-dev or binutils-devel        # contains GNU bfd for printing stack traces
   gcc or clang                          # see above
   git                                   # see above
   uuid-dev                              # optional, for box_uuid_* functions
   cmake                                 # see above
   libreadline-dev                       # optional, for build with -DENABLE_CLIENT
   libncurses5-dev or ncurses-devel      # optional, for build with -DENABLE_CLIENT
   xsltproc                              # optional, for build with -DENABLE_DOC
   lynx                                  # optional, for build with -DENABLE_DOC
   jing                                  # optional, for build with -DENABLE_DOC
   libxml2-utils                         # optional, for build with -DENABLE_DOC
   docbook5-xml                          # optional, for build with -DENABLE_DOC
   docbook-xsl-ns                        # optional, for build with -DENABLE_DOC
   w3c-sgml-lib                          # optional, for build with -DENABLE_DOC
   libsaxon-java                         # optional, for build with -DENABLE_DOC
   libxml-commons-resolver1.1-java       # optional, for build with -DENABLE_DOC
   libxerces2-java                       # optional, for build with -DENABLE_DOC
   libxslthl-java                        # optional, for build with -DENABLE_DOC
   autoconf                              # optional, appears only in Mac OS scripts
   zlib1g or zlib                        # optional, appears only in Mac OS scripts

2. Pick a default directory. This can be anywhere. We'll assume that your default directory is “~”, and therefore the tarantool download will go inside it, as ~/tarantool.

3. Use git to download from github.com.

cd ~
git clone -b stable https://github.com/tarantool/tarantool.git tarantool

The optional argument “-b stable” causes download from the stable branch instead of the master branch, and the optional last word on the line, “tarantool”, means download is to ~/tarantool.

4. Use git again so that third-party contributions will be seen as well. This step is only necessary once, the first time you do a download. There is an alternative -- say “git clone --recursive” in step 3 -- but we prefer this method because it works with older versions of git.

cd ~/tarantool
git submodule init
git submodule update
cd ../

5. Use CMake to initiate the build.

cd ~/tarantool
make clean         # unnecessary, added for good luck
rm CMakeCache.txt  # unnecessary, added for good luck
cmake .            # The command to initiate with build type=Debug, no client, no doc

The option for specifying build type is -DCMAKE_BUILD_TYPE=type where type = {None | Debug | Release | RelWithDebInfo | MinSizeRel} and a reasonable choice for production is -DCMAKE_BUILD_TYPE=RelWithDebInfo (“Debug” is used only by project maintainers and “Release” is used only when the highest performance is required). The option for asking to build client is -DENABLE_CLIENT={true|false} and a reasonable choice is -DENABLE_CLIENT=true. The option for asking to build documentation is -DENABLE_DOC={true|false} and the assumption is that only a minority will need to rebuild the documentation (such as what you're reading now), so details about documentation are in the developer manual, and the reasonable choice is -DENABLE_DOC=false or just don't use the -DENABLE_DOC clause at all.

6. Use make to complete the build.

make

It's possible to say “make install” too, but that's not generally done.

7. Set up python modules for running the test suite. This step is optional.

Say:

python --version

... You should see that the python version is between 2.6 and 3.

On Ubuntu you can get modules from the repository:

sudo apt-get install python-daemon python-yaml python-argparse python-pexpect

On CentOS too you can get modules from the repository:

sudo yum install python26 python26-PyYAML python26-argparse

But in general it is best to set up the modules by getting a tarball and doing the setup with python setup.py, thus:

# python module for parsing YAML (pyYAML):
# (If wget fails, check the PyYAML web site to see what the current version is.)
cd ~
wget http://pyyaml.org/download/pyyaml/PyYAML-3.10.tar.gz
tar -xzf PyYAML-3.10.tar.gz
cd PyYAML-3.10
sudo python setup.py install
# python module for spawning child applications (pexpect):
# (If wget fails, check the  python-pexpect web site to see what the current version is.)
cd ~
wget http://pypi.python.org/packages/source/p/pexpect-u/pexpect-u-2.5.1.tar.gz
tar -xzvf pexpect-u-2.5.1.tar.
cd pexpect-u-2.5.1
sudo python setup.py install
# python module for assisting programs to turn themselves into daemons (daemon):
# (if wget fails, check the python-daemon web site to see what the current version is.)
cd ~
wget http://pypi.python.org/packages/source/d/daemon/daemon-1.0.tar.gz
tar -xzvf daemon-1.0.tar.gz
cd daemon-1.0
sudo python setup.py install

8. Run the test suite. This step is optional.

Tarantool's developers always run the test suite before they publish new versions. You should run the test suite too, if you make any changes in the code. Assuming you downloaded to ~/tarantool, the principal steps are:

mkdir ~/tarantool/bin    # make a subdirectory named bin
ln usr/bin/python ~/tarantool/bin/python # link python to bin
cd ~/tarantool/test #get on the test subdirectory
PATH=~/tarantool/bin:$PATH ./run #run tests using python

The output should contain reassuring reports, for example

======================================================================
TEST                                             RESULT
------------------------------------------------------------
box/admin.test                                  [ pass ]
box/admin_coredump.test                         [ pass ]
box/args.test                                   [ pass ]
box/cjson.test                                  [ pass ]
box/configuration.test                          [ pass ]
box/errinj.test                                 [ pass ]
box/fiber.test                                  [ pass ]
... etc.

There are more than 70 tests in the suite. To prevent later confusion, clean up what's in the bin subdirectory:

rm ~/tarantool/bin/python
rmdir ~/tarantool/bin

9. Make an rpm. This step is optional. It's only for people who want to redistribute Tarantool. Ordinarily it should be skipped. It will add a new subdirectory: ~/tarantool/RPM.

make rpm

This is the end of the list of steps to take for source downloads.

For your added convenience, github.com has README files with example scripts: README.CentOS for CentOS 5.8, README.FreeBSD for FreeBSD 8.3, README.MacOSX for Mac OS X “Lion”, README.md for generic GNU/Linux. These example scripts assume that the intent is to download from the master branch, build the server and the client (but not the documentation), and run tests after build.

To build with SUSE 13.1, the steps are as described above, except that the appropriate YaST2 package names are: binutils-devel, libuuid-devel, cmake, ncurses-devel, lynx, jing, libxml2-devel, docbook_5, saxon, libxslt-devel. The python connector can be installed with sudo easy_install pip and sudo pip install tarantool.

Here is how to create a simple test database after installing.

1. Create a new directory. It's just for tests, you can delete it when the tests are over.

mkdir ~/tarantool_sandbox
cd ~/tarantool_sandbox
mkdir work_dir

2. Create a configuration file. The Tarantool server requires a configuration file with some definitions of ports and database objects. The server, by default, looks for its configuration file in the current working directory and in etc/. Enter the following commands which make a minimal configuration file that will be suitable for day one.

echo "slab_alloc_arena = 0.1" | tee tarantool.cfg
echo "pid_file = \"box.pid\"" | tee -a tarantool.cfg
echo "primary_port = 33013" | tee -a tarantool.cfg
echo "secondary_port = 33014" | tee -a tarantool.cfg
echo "admin_port = 33015" | tee -a tarantool.cfg
echo "rows_per_wal = 50000" | tee -a tarantool.cfg
echo "space[0].enabled = 1" | tee -a tarantool.cfg
echo "space[0].index[0].type = \"HASH\"" | tee -a tarantool.cfg
echo "space[0].index[0].unique = 1" | tee -a tarantool.cfg
echo "space[0].index[0].key_field[0].fieldno = 0" | tee -a tarantool.cfg
echo "space[0].index[0].key_field[0].type = \"NUM\"" | tee -a tarantool.cfg
echo "logger = \"tee --append tarantool.log\"" | tee -a tarantool.cfg
echo "work_dir = \"work_dir\"" | tee -a tarantool.cfg
(With some downloads a tarantool.cfg file like this is already available in a test subdirectory.)

Initialize the storage area. You only have to do this once.

/usr/bin/tarantool_box --init-storage            #if you downloaded a binary with apt-get or yum
~/tarantool/bin/tarantool_box --init-storage     #if you downloaded and untarred a binary tarball to ~/tarantool
~/tarantool/src/box/tarantool_box --init-storage #f you built from a source download 

Start the server. The server name is tarantool_box.

/usr/bin/tarantool_box             #if you downloaded a binary with apt-get or yum
~/tarantool/bin/tarantool_box     	#if you downloaded and untarred a binary tarball to ~/tarantool
~/tarantool/src/box/tarantool_box 	#f you built from a source download

If all goes well, you will see the server displaying progress as it initializes, something like this:

2013-10-18 20:20:36.806 [16560] 1/sched C> version 1.5.1-141-ga794d35
2013-10-18 20:20:36.830 [16560] 1/sched I> Loading plugin: /usr/lib/tarantool/plugins/libmysql.so
2013-10-18 20:20:37.016 [16560] 1/sched I> Plugin 'mysql' was loaded, version: 1
2013-10-18 20:20:37.016 [16560] 1/sched I> Loading plugin: /usr/lib/tarantool/plugins/libpg.so
2013-10-18 20:20:37.044 [16560] 1/sched I> Plugin 'postgresql' was loaded, version: 1
2013-10-18 20:20:37.044 [16560] 1/sched I> space 0 successfully configured
2013-10-18 20:20:37.044 [16560] 1/sched I> recovery start
2013-10-18 20:20:37.060 [16560] 1/sched I> recover from `./00000000000000000001.snap'
2013-10-18 20:20:37.060 [16560] 1/sched I> snapshot recovered, confirmed lsn: 1
2013-10-18 20:20:37.070 [16560] 1/sched I> done `./00000000000000000002.xlog' confirmed_lsn: 2
2013-10-18 20:20:37.070 [16560] 1/sched I> WALs recovered, confirmed lsn: 2
2013-10-18 20:20:37.070 [16560] 1/sched I> building secondary indexes
2013-10-18 20:20:37.070 [16560] 1/sched I> bound to primary port 33013
2013-10-18 20:20:37.070 [16560] 1/sched I> I am primary
2013-10-18 20:20:37.070 [16560] 1/sched I> bound to secondary port 33014
2013-10-18 20:20:37.070 [16560] 1/sched I> bound to admin port 33015
2013-10-18 20:20:37.071 [16560] 1/sched C> log level 4
2013-10-18 20:20:37.071 [16560] 1/sched C> entering event loop

Now take the server down, with

Ctrl+C

Now start the server again. This time start it in the background.

/usr/bin/tarantool_box --background             #if you downloaded a binary with apt-get or yum
~/tarantool/bin/tarantool_box --background     	#if you downloaded and untarred a binary tarball to ~/tarantool
~/tarantool/src/box/tarantool_box --background 	#f you built from a source download

If all went well, there is now an instance of the Tarantool server running in the background. You can confirm that with the command:

ps -a | grep tarantool_box

or look at the log file:

less work_dir/tarantool.log

Please follow distribution-specific instructions to find out how to manage Tarantool instances on your operating system.

$ ./test/run --start-and-exit

Now that the server is up, you can start the client. The client name is tarantool.

/usr/bin/tarantool                      #If you downloaded a binary with apt-get or yum:  
~/tarantool/bin/tarantool               #If you downloaded and untarred a binary tarball to ~/tarantool:  
~/tarantool/client/tarantool/tarantool  #If you built from a source download on ~tarantool

If all goes well, a prompt will appear:

localhost>

The client is waiting for the user to type instructions.

To insert three “tuples” (our name for “records”) into the first “space” of the database (which is called t0), try this:

localhost> INSERT INTO t0 VALUES (1)
localhost> INSERT INTO t0 VALUES (2,'Music')
localhost> INSERT INTO t0 VALUES (3,'length',93)

To select a tuple from the first space of the database, using the first defined key (which is called k0), try this:

localhost> SELECT * FROM t0 WHERE k0 = 3

Your terminal screen should now look like this:

localhost> INSERT INTO t0 VALUES (1)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (2,'Music')
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (3,'Length',93)
Insert OK, 1 rows affected
localhost> SELECT * FROM t0 WHERE k0 = 3
Select OK, 1 rows affected
[3, 'Length', 93]
localhost>>

You can repeat INSERT and SELECT indefinitely. When the testing is over: To stop the client: Ctrl+C. To stop the server: sudo pkill -f tarantool_box. To destroy the test: rm -r ~/tarantool_sandbox.

If you tried out the “Starting Tarantool and making your first database” exercise from the last chapter, then your database looks like this:

+--------------------------------------------+
|                                            |
| SPACE 'space[0]'                           |
| +----------------------------------------+ |
| |                                        | |
| | TUPLE SET 't0'                         | |
| | +-----------------------------------+  | |
| | | Tuple: [ 1 ]                      |  | |
| | | Tuple: [ 2, 'Music' ]             |  | |
| | | Tuple: [ 3, 'length', 93 ]        |  | |
| | +-----------------------------------+  | |
| |                                        | |
| | INDEX 'index[0]'                       | |
| | +-----------------------------------+  | |
| | | Key: 1                            |  | |
| | | Key: 2                            |  | |
| | | Key: 3                            |  | |
| | +-----------------------------------+  | |
| |                                        | |
| +----------------------------------------+ |
+--------------------------------------------+

Space

A space -- 'space[0]' in the example -- is a container.

There is always at least one space; there can be many spaces, numbered as space[0], space[1], and so on. Spaces always contain one tuple set and one or more indexes.

Tuple Set

A tuple set -- 't0' in the example -- is a group of tuples.

There is always one tuple set in a space. For the tarantool client, the identifier of a tuple set is “t” followed by the space's number, for example “t0” refers to the tuple set of space[0]. (The letter “t” stands for “tuple set.”)

A tuple fills the same role as a “row” or a “record”, and the components of a tuple (which we call “fields”) fill the same role as a “row column” or “record field”, except that: the fields of a tuple don't need to have names. That's why there was no need to pre-define the tuple set in the configuration file, and that's why each tuple can have a different number of elements, and that's why we say that Tarantool has a “dynamic” data model.

Any given tuple may have any number of fields and the fields may have any of these three types: NUM (32-bit unsigned integer between 0 and 2,147,483,647), NUM64 (64-bit unsigned integer between 0 and 18,446,744,073,709,551,615), or STR (string, any sequence of octets). The identifier of a field is “k” followed by the field's number, for example “k0” refers to the first field of a tuple.

When the tarantool client displays a tuple, it surrounds strings with single quotes, separates fields with commas, and encloses the tuple inside square brackets. For example: [ 3, 'length', 93 ].

Index

An index -- 'index[0]' in the example -- is a group of key values and pointers.

There is always at least one index in a space; there can be many. The identifier of an index is 'index' followed by the index's number within the space, so in our example there is one index and its identifier is “index[0]”.

An index may be multi-field, that is, the user can declare that an index key value is taken from two or more fields in the tuple, in any order. An index may be unique, that is, the user can declare that it would be illegal to have the same key value twice. An index may have one of three types: HASH which is fastest and uses the least memory but must be unique, TREE which allows partial-key searching and ordered results, and BITSET which can be good for searches that contain '=' and 'AND' in the WHERE clause. The first index -- index[0] -- is called the “primary key” index and it must be unique; all other indexes -- index[1], index[2], and so on -- are “secondary” indexes.

An index definition always includes at least one identifier of a tuple field and its expected type. Take our example configuration file, which has the lines:

space[0].index[0].key_field[0].fieldno = 0
space[0].index[0].key_field[0].type = "NUM"

The effect is that, for all tuples in t0, field number 0 (k0) must exist and must be a 32-bit unsigned integer.

For the current version of the Tarantool server, space definitions and index definitions must be in the configuration file. Administrators must take care that what's in the configuration file matches what's in the database. If a server is started with the wrong configuration file, it could behave in an unexpected way or crash. However, it is possible to stop the server or disable database accesses, then add new spaces and indexes, then restart the server or re-enable database accesses. The syntax details for defining spaces and indexes are in chapter 7 Configuration reference.

Operations

The basic operations are: the four data-change operations (INSERT, UPDATE, DELETE, REPLACE), and the data-retrieval operation (SELECT). There are also minor operations like “ping” which are not available via the tarantool client's SQL-like interface but can only be used with the binary protocol. Also, there are index iterator operations, which can only be used with Lua stored procedures. (Index iterators are for traversing indexes one key at a time, taking advantage of features that are specific to an index type, for example evaluating Boolean expressions when traversing BITSET indexes, or going in descending order when traversing TREE indexes.)

Five examples of basic operations:

/* Add a new tuple to tuple set t0.
   The first field, k0, will be 999 (type is NUM).
   The second field, k1, will be 'Taranto' (type is STR). */
INSERT INTO t0 VALUES (999,'Taranto')

/* Update the tuple, changing field k1.
   The clause "WHERE primary-key-field-identifier = value is mandatory
   because UPDATE statements must always have a WHERE clause that
   specifies the primary key, which in this case is k0. */
UPDATE t0 SET k1 = 'Tarantino' WHERE k0 = 999

/* Replace the tuple, adding a new field.
   This is not possible with the UPDATE statement because
   the SET clause of an UPDATE statement can only refer to
   fields that already exist. */
REPLACE INTO t0 VALUES (999,'Tarantella',Tarantula')

/* Retrieve the tuple.
   The WHERE clause is still mandatory, although it does not have to
   mention the primary key. */
SELECT * FROM t0 WHERE k0 = 999

/* Delete the tuple.
   Once again the clause "WHERE k0 = value is mandatory. */
DELETE FROM t0 WHERE k0 = 999

How does Tarantool do a basic operation? Let's take this example:

UPDATE t0 SET k1 = 'size', k2=0 WHERE k0 = 3

STEP #1: the client parses the statement and changes it to a binary-protocol instruction which has already been checked, and which the server can understand without needing to parse everything again. The client ships a packet to the server.

STEP #2: the server's “transaction processor” thread uses the primary-key index on field k0 to find the location of the tuple in memory. It determines that the tuple can be updated (not much can go wrong when you're merely changing an unindexed field value to something shorter).

STEP #3: the transaction processor thread sends a message to the write-ahead logging (WAL) thread.

At this point a “yield” takes place. To know the significance of that -- and it's quite significant -- you have to know a few facts and a few new words.

FACT #1: there is only one transaction processor thread. Some people are used to the idea that there can be multiple threads operating on the database, with (say) thread #1 reading row #x while thread#2 writes row#y. With Tarantool no such thing ever happens. Only the transaction processor thread can access the database, and there is only one transaction processor thread for each instance of the server.

FACT #2: the transaction processor thread can handle many fibers. A fiber is a set of computer instructions that may contain “yield” signals. The transaction processor thread will execute all computer instructions until a yield, then switch to execute the instructions of a different fiber. Thus (say) the thread reads row#x for the sake of fiber#1, then writes row#y for the sake of fiber#2.

FACT #3: yields must happen, otherwise the transaction processor thread would stick permanently on the same fiber. There are implicit yields: every data-change operation or network-access causes an implicit yield, and every statement that goes through the tarantool client causes an implicit yield. And there are explicit yields: in a Lua stored procedure one can and should add “yield” statements to prevent hogging. This is called cooperative multitasking.

Since all data-change operations end with an implicit yield and an implicit commit, and since no data-change operation can change more than one tuple, there is no need for any locking. Consider, for example, a stored procedure that does three operations:

SELECT              /* this does not yield and does not commit */
UPDATE              /* this yields and commits */
SELECT              /* this does not yield and does not commit */

The combination “SELECT plus UPDATE” is an atomic transaction: the stored procedure holds a consistent view of the database until the UPDATE ends. For the combination “UPDATE plus SELECT” the view is not consistent, because after the UPDATE the transaction processor thread can switch to another fiber, and delete the tuple that was just updated.

Since locks don't exist, and disk writes only involve the write-ahead log, transactions are usually fast. Also the Tarantool server may not be using up all the threads of a powerful multi-core processor, so advanced users may be able to start a second Tarantool server on the same processor without ill effects.

Additional examples of SQL statements can be found in the Tarantool regression test suite. A complete grammar of supported SQL is provided in the Language reference chapter.

Since not all Tarantool operations can be expressed in SQL, to gain complete access to data manipulation functionality one must use a Perl, Python, Ruby or other programming language connector. The client/server protocol is open and documented: an annotated BNF can be found in the source tree, file doc/protocol.txt.

To maintain data persistence, Tarantool writes each data change request (INSERT, UPDATE, DELETE) into a write-ahead log (WAL) file in the wal_dir directory. A new WAL file is created for every rows_per_wal records. Each data change request gets assigned a continuously growing 64-bit log sequence number. The name of the WAL file is based on the log sequence number of the first record in the file, plus an extension .xlog.

Apart from a log sequence number and the data change request (its format is the same as in the binary protocol and is described in doc/box-protocol.txt), each WAL record contains a checksum and a UNIX time stamp. For example this is what the WAL file looks like after the first INSERT statement ("INSERT INTO t0 VALUES (1)") for the introductory sandbox exercise “Starting Tarantool and making your first database”. On the left are the hexadecimal bytes that one would see with

$ hexdump work_dir/00000000000000000002.xlog

and on the right are comments.

Hex dump of WAL file        Comment
--------------------        -------
58 4c 4f 47 0a              File header: "XLOG\n"
30 2e 31 31 0a 0a           File header: "0.11\n\n" = version
ed ab 0b ba                 Magic row marker always = 0xba0babed for version 0.11
10 2a 1b 5e                 Record header: crc32 checksum of header fields
02 00 00 00 00 00 00 00     Record header: 2 = (64-bit int) log sequence number
99 c8 f1 d9 32 a8 d4 41     Record header: (double) unix time-since-epoch for transaction
1d 00 00 00                 Record header: 29 = length of rest of record, non-inclusive
60 45 94 cd                 Record header: crc32 checksum of data fields
fe ff                       Tag = XLOG which is #defined as 65534
02 00 99 f9 7f 00 00 01     Session cookie, comes from struct sockaddr_in *addr
0d 00 00 00                 Data change request code = insert which is #defined as 13
00 00                       Space number = 0
02 00 00 00                 Flags = BOX_ADD which is defined as 2
01 00 00 00                 Tuple: Count of fields in tuple = 1
04                          Tuple: field[0] length = 4 because value is 4 bytes long
01 00 00 00                 Tuple: field[0] value = 1

Tarantool processes requests atomically: a change is either accepted and recorded in the WAL, or discarded completely. Let's clarify how this happens, using REPLACE command as an example:

One advantage of the described algorithm is that complete request pipelining is achieved, even for requests on the same value of the primary key. As a result, database performance doesn't degrade even if all requests touch upon the same key in the same space.

The transaction processor and the WAL writer threads communicate using asynchronous (yet reliable) messaging; the transaction processor thread, not being blocked on WAL tasks, continues to handle requests quickly even at high volumes of disk I/O. A response to a request is sent as soon as it is ready, even if there were earlier incomplete requests on the same connection. In particular, SELECT performance, even for SELECTs running on a connection packed with UPDATEs and DELETEs, remains unaffected by disk load.

The WAL writer employs a number of durability modes, as defined in configuration variable wal_mode. It is possible to turn the write ahead log completely off, by setting wal_mode to none. Even without the write ahead log it's still possible to take a persistent copy of the entire data set with the SAVE SNAPSHOT statement.

Five basic request types are supported: INSERT, UPDATE, DELETE, SELECT and CALL. All requests, including INSERT, UPDATE and DELETE may return data. A SELECT can be requested to limit the number of returned tuples. This is useful when searching in a non-unique index or when a special “wildcard” (zero-length string) value is supplied as search key or a key part.

UPDATE statement supports operations on fields — assignment, arithmetic operations (the field must be numeric), cutting and pasting fragments of a field, — as well as operations on a tuple: push and pop of a field at the tail of a tuple, deletion and insertion of a field. Multiple operations can be combined into a single update, and in this case they are performed atomically. Each operation expects field number as its first argument. When a sequence of changes is present, field identifier in each operation is assumed to be relative to the most recent state of the tuple, i.e. as if all previous operations in a multi-operation update have already been applied. In other words, it's always safe to merge multiple UPDATE statements into a single one, with no change in semantics.

Tarantool protocol was designed with focus on asynchronous I/O and easy integration with proxies. Each client request starts with a 12-byte binary header, containing three fields: request type, length, and a numeric id.

The mandatory length, present in request header simplifies client or proxy I/O. A response to a request is sent to the client as soon as it is ready. It always carries in its header the same type and id as in the request. The id makes it possible to match a request to a response, even if the latter arrived out of order.

Request type defines the format of the payload. INSERTs, UPDATEs and DELETEs can only be made by the primary key, so an index id and a key (possibly multipart) are always present in these requests. SELECTs can use secondary keys. UPDATE only needs to list the fields that are actually changed. With this one exception, all commands operate on whole tuple(s).

Unless implementing a client driver, one needn't concern oneself with the complications of the binary protocol. Language-specific drivers provide a friendly way to store domain language data structures in Tarantool, and the command line client supports a subset of standard SQL. A complete description of both, the binary protocol and the supported SQL, is maintained in annotated Backus-Naur form in the source tree: please see doc/box-protocol.txt and doc/sql.txt respectively.

The administrative console uses a simple text protocol. All commands are case-insensitive. You can connect to the administrative port using any telnet client, or a tool like rlwrap, if access to readline features is desired. Additionally, tarantool, the SQL-capable command line client, understands all administrative statements and automatically directs them to the administrative port. The server response to an administrative command, even though it is always in plain text, can be quite complex. It is encoded using YAML markup to simplify automated parsing.

To learn about all supported administrative commands, you can type help in the administrative console. A reference description also follows below:

Procedures can be invoked from the administrative console and using the binary protocol, for example:

localhost> lua function f1() return 'hello' end
---
...
localhost> call f1()
Call OK, 1 rows affected
['hello']

In the language of the administrative console LUA ... evaluates an arbitrary Lua chunk. CALL is an SQL standard statement, so its syntax was adopted by Tarantool command line client to invoke the CALL command of the binary protocol.

In the example above, "lua function f1() return 'hello' end" defines a Lua procedure using the text protocol of the administrative port, and "call f1()" invokes the procedure using the Tarantool client-side SQL parser plus the binary protocol on the primary_port. Since it's possible to execute any Lua chunk in the administrative console, the newly created function f1() can be invoked there too:

localhost> lua f1()
---
 - hello
...
localhost> lua 1+2
---
 - 3
...
localhost> lua "hello".." world"
---
 - hello world
...

Lua procedures could also be called at the time of initialization using a dedicated init.lua script, located in script_dir. An example of such a script is given below:

    
-- Importing expirationd module
dofile("expirationd.lua")

function is_expired(args, tuple)
   if tuple == nil then
       return true
   end

   if #tuple <= args.field_no then
       return true
   end

   field = tuple[args.field_no]
   if field == nil or #field ~= 4 then
       return true
   end

   local current_time = os.time()
   local tuple_ts = box.unpack("i", field)
   return current_time >= tuple_ts + args.ttl
end
function purge(args, tuple)
    box.space[0]:delete(tuple[0])
end

-- Run task
expirationd.run_task("exprd space 0", 0, is_expired, purge,
                    { field_no = 1, ttl = 30 * 60 })

    

The initialization script can select and modify data. However, if the server is a running replica, data change requests from the start script fail just the same way they would fail if they were sent from a remote client.

Another common task to perform in the initialization script is to start background fibers for data expiration, re-sharding, or communication with networked peers.

Finally, the script can be used to define Lua triggers invoked on various events within the system.

There is a single global instance of the Lua interpreter, which is shared across all connections. Anything prefixed with lua on the administrative console is sent directly to this interpreter. Any change of the interpreter state is immediately available to all client connections.

Each connection, however, is using its own Lua coroutine — a mechanism akin to Tarantool fibers. A coroutine has an own execution stack and a Lua closure — set of local variables and definitions.

The interpreter environment is not restricted when init.lua is loaded. But before the server starts accepting requests, the standard Lua APIs, such as for file I/O, process control and module management are unset, to avoid possible trivial security attacks.

In the binary protocol, it's only possible to call existing procedures, but not define or alter them. The CALL request packet contains the command code for CALL (22), the name of a procedure to be called, and a tuple for procedure arguments. Currently, Tarantool tuples are type-agnostic, thus each field of the tuple is passed into the procedure as an argument of type “string”. For example:

kostja@atlas:~$ cat arg.lua
function f1(a)
    local s = a
    if type(a) == 'string' then
        s = ''
        for i=1, #a, 1 do
            s = s..string.format('0x%x ', string.byte(a, i))
        end
    end
    return type(a), s
end
kostja@atlas:~$ tarantool
localhost> lua dofile('arg.lua')
---
...
localhost> lua f1('1234')
---
 - string
 - 0x31 0x32 0x33 0x34
...
localhost> call f1('1234')
Call OK, 2 rows affected
['string']
['0x31 0x32 0x33 0x34 ']
localhost> lua f1(1234)
---
 - number
 - 1234
...
localhost> call f1(1234)
Call OK, 2 rows affected
['string']
['0xd2 0x4 0x0 0x0 ']

In the above example, the way the procedure receives its argument is identical in the two protocols, when the argument is a string. A numeric field, however, when submitted via the binary protocol, is seen by the procedure as a 4-byte blob, not as a Lua “number” type.

In addition to conventional method invocation, Lua provides object-oriented syntax. Access to the latter is available on the administrative console only:

localhost> lua box.space[0]:truncate()
---
...
localhost> call box.space[0]:truncate()
error: 1:15 expected '('

Since it's impossible to invoke object methods from the binary protocol, the object-oriented syntax is often used to restrict certain operations to be used by a system administrator only.

Every value, returned from a stored function by means of a return clause, is converted to a Tarantool tuple. Tuples are returned as such, in binary form; a Lua scalar, such as a string or an integer, is converted to a tuple with only one field. When the returned value is a Lua table, the resulting tuple contains only table values, but not keys.

When a function in Lua terminates with an error, the error is sent to the client as ER_PROC_LUA return code, with the original error message preserved. Similarly, an error which has occurred inside Tarantool (observed on the client as an error code), when it happens during execution of a Lua procedure, produces a genuine Lua error:

localhost> lua function f1() error("oops") end
---
...
localhost> call f1()
Call ERROR, Lua error: [string "function f1() error("oops") end"]:1: oops (ER_PROC_LUA)
localhost> call box.insert('99', 1, 'test')
Call ERROR, Space 99 is disabled (ER_SPACE_DISABLED)
localhost> lua pcall(box.insert, 99, 1, 'test')
---
 - false
 - Space 99 is disabled
...

It's possible not only to invoke trivial Lua code, but call into Tarantool storage functionality, using the box Lua library. The contents of the library can be inspected at runtime:

localhost> lua for k, v in pairs(box) do print(k, ": ", type(v)) end
---
fiber: table
space: table
cfg: table
on_reload_configuration: function
update: function
process: function
delete: function
insert: function
select: function
index: table
unpack: function
replace: function
select_range: function
pack: function
...

As is shown in the listing, the box package contains:

localhost> setopt delimiter = '!'
localhost> lua function function_x ()
        ->   box.fiber.detach()
        ->   gvar = 0
        ->   while 0 == 0 do
        ->     gvar = gvar + 1
        ->     box.fiber.sleep(2)
        ->     end
        ->   end!
---
...
localhost> setopt delimiter = ''!

localhost> lua fiber_of_x = box.fiber.create(function_x)
---
...
localhost> lua fid = box.fiber.id(fiber_of_x)
---
...

localhost> lua box.fiber.resume(fiber_of_x)
---
...

localhost> lua print("fiber=",fid,". ",box.fiber.status(fiber_of_x),". gvar=",gvar)
---
fiber=104. suspended. gvar=9
...

localhost> lua box.fiber.cancel(fiber_of_x)
---
...
localhost> lua print("fiber=",fid,". ",box.fiber.status(fiber_of_x),". gvar=",gvar)
---
fiber=104. dead. gvar=22
...

localhost> lua box.session.peer(box.session.id())
---
 - 127.0.0.1:45129
...
localhost> lua box.session.storage.random_memorandum = "Don't forget to buy eggs."
---
...
localhost> lua box.session.storage.radius_of_mars = 3396
---
...
localhost> lua for k,v in pairs(box.session.storage) do print(k,' ',v) end
---
radius_of_mars 3396
random_memorandum Don't forget to buy eggs.
...

local channel = box.ipc.channel(10)
function consumer_fiber()
    while true do
        local task = channel:get()
        ...
    end
end

function consumer2_fiber()
    while true do
        local task = channel:get(10)        -- 10 seconds
        if task ~= nil then
            ...
        else
            print("timeout!")
        end
    end
end

function producer_fiber()
    while true do
        task = box.select(...)
        ...
        if channel:is_empty() then
            # channel is empty
        end

        if channel:is_full() then
            # channel is full
        end

        ...
        if channel:has_readers() then
            # there are some fibers that wait are waiting for data
        end
        ...

        if channel:has_writers() then
            # there are some fibers that are waiting for readers
        end
        channel:put(task)
    end
end

function producer2_fiber()
    while true do
        task = box.select(...)

        if channel:put(task, 10) then       -- 10 seconds
            ...
        else
            print("timeout!")
        end
    end
end

localhost>  setopt delimiter = '!'
localhost>  lua function example()
        ->    if self:ping() then
        ->      print("self:ping() succeeded (not surprising since self is a pre-established connection).")
        ->      end
        ->    if box.cfg.primary_port == 33013 then
        ->      print('The local server primary port number is 33013 (the default)')
        ->    else
        ->      print('The local server primary port number is not 33013, so connect will fail')
        ->      end
        ->    conn = box.net.box.new('127.0.0.1', 33013)
        ->    conn:delete(0,800)
        ->    print('conn:delete done on space[0].')
        ->    conn:insert(0,800,'data')
        ->    print('conn:insert done on space[0], index 0. primary key value = 800.')
        ->    wtuple = conn:select(0,0,800)
        ->    print('conn:select done on space[0], index 0. number of fields = ', #wtuple)
        ->    conn:delete(0,800)
        ->    print('conn:delete done on space[0].')
        ->    conn:replace(0,800,'New data','Extra data')
        ->    print('conn:replace done on space[0].')
        ->    conn:timeout(0):update(0,800,'=p=p=p',1, 'Field#1', 2,'Field#2', 3,'Field#3')
        ->    print('conn:update done on space[0], timed out after waiting 0 seconds for a return')
        ->    conn:close()
        ->    print('conn:close done')
        ->  end!
---
...
localhost>  setopt delimiter = ''!
localhost>  lua example()
---
self:ping() succeeded (not surprising since self is a pre-established connection).
The local server primary port number is 33013 (the default)
conn:delete done on space[0].
conn:insert done on space[0], index 0. primary key value = 800.
conn:select done on space[0], index 0. number of fields = 2
conn:delete done on space[0].
conn:replace done on space[0].
conn:update done on space[0], timed out after waiting 0 seconds for a return
conn:close done
...
localhost>  select * from t0 where k0 = 800 # Prove that the update succeeded.
Select OK, 1 rows affected
[800, 'Field#1', 'Field#2', 'Field#3']

A replica gets all updates from the master by continuously fetching and applying its write ahead log (WAL). Each record in the WAL represents a single Tarantool command such as INSERT or UPDATE or DELETE, and is assigned a monotonically growing log sequence number (LSN). In essence, Tarantool replication is row-based: all data change commands are fully deterministic and operate on a single record.

A stored program invocation does not enter the Write Ahead Log. Instead, log events for actual UPDATEs and DELETEs, performed by the Lua code, are written to the log. This ensures that possible non-determinism of Lua does not cause replication to go out of sync.

For replication to work correctly, the latest LSN on the replica must match or fall behind the latest LSN on the master. If the replica had its own updates, this would lead to it getting out of sync, since updates from the master having identical LSNs would not be applied. In fact, if replication is ON, Tarantool does not accept updates, even on its primary_port.

To prepare the master for connections from the replica, it's only necessary to enable replication_port in the configuration file. An example configuration file can be found in test/replication/cfg/master.cfg. A master with enabled replication_port can accept connections from as many replicas as necessary on that port. Each replica has its own replication state.

A server, whether master or replica, always requires a valid snapshot file to boot from. For a master, a snapshot file is usually prepared with with the --init-storage option. For a replica, it's usually copied from the master.

To start replication, configure replication_source. Other parameters can also be changed, but existing spaces and their primary keys on the replica must be identical to the ones on the master.

Once connected to the master, the replica requests all changes that happened after the latest local LSN. It is therefore necessary to keep WAL files on the master host as long as there are replicas that haven't applied them yet. An example configuration can be found in test/replication/cfg/replica.cfg.

If required WAL files are absent, a replica can be "re-seeded" at any time with a newer snapshot file, manually copied from the master.

"Degraded state" is a situation when the master becomes unavailable -- due to hardware or network failure, or due to a programming bug. There is no reliable way for a replica to detect that the master is gone for good, since sources of failure and replication environments vary significantly.

A separate monitoring script (or scripts, if a decision-making quorum is desirable) is necessary to detect a master failure. Such a script would typically try to update a tuple in an auxiliary space on the master, and raise an alarm if a network or disk error persists for longer than is acceptable.

When a master failure is detected, the following needs to be done:

The server is configured to gracefully shutdown on SIGTERM and SIGINT (keyboard interrupt) or SIGHUP. SIGUSR1 can be used to save a snapshot. All other signals are blocked or ignored. The signals are processed in the main event loop. Thus, if the control flow never reaches the event loop (thanks to a runaway stored procedure), the server stops responding to any signal, and can be only killed with SIGKILL (this signal can not be ignored).

This section shows all legal syntax for the tarantool command-line client, with short notes and examples. Other client programs may have similar options and statement syntaxes.

Conventions used in this section

Tokens are character sequences which are treated as syntactic units within statements. Square brackets [ and ] enclose optional syntax. Three dots in a row ... mean the preceding tokens may be repeated. A vertical bar | means the preceding and following tokens are mutually exclusive alternatives.

Options when starting client from the command line

General form: tarantool [option...] [statement]. Statement will be described in a later part of this section. Option is one of the following (in alphabetical order by the long form of the option):

Tokens for use within statements

Keywords are: Character sequences containing only letters of the English alphabet. Examples: SELECT, INTO, FIBER. Notes: Keywords are case insensitive so SELECT and Select are the same thing.

Tuple set identifiers are: Lower case letter 't' followed by one or more digits. Examples: t0, t55.

Field identifiers are: Lower case letter 'k' followed by one or more digits. Examples: k0, k55.

Procedure identifiers are: Any sequence of letters, digits, or underscores which is legal according to the rules for Lua identifiers.

String literals are: Any sequence of zero or more characters enclosed in single quotes. Examples: 'Hello, world', 'A'.

Numeric literals are: Character sequences containing only digits, optionally preceded by + or -. Examples: 55, -. Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.

Single-byte tokens are: * or , or ( or ). Examples: * , ( ).

Tokens must be separated from each other by one or more spaces, except that spaces are not necessary around single-byte tokens or string literals.

Statements in alphabetical order

Although an initial statement may be entered on the tarantool command line, generally they are entered following the prompt in interactive mode while tarantool is running. (A prompt will be the name of the host and a greater-than sign, for example localhost>). The end-of-statement marker is a newline (line feed).

For a condensed Backus-Naur Form [BNF] description of some of the statements, see doc/box-protocol.txt and doc/sql.txt.

Modes

Depending how one combines the tarantool client's options, there are in effect three modes of operation: “interactive”, “print and play”, or “replication” mode.

In interactive mode, one types statements and gets results. One can specify a statement file when starting (tarantool < file_name) or one can specify a statement file with the LOADFILE statement: (LOADFILE file_name), but typically the statements are typed in by the user following prompts. Here is an example of an interactive-mode tarantool client session:

$ tarantool
localhost> INSERT INTO t0 VALUES ('X-1',100)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES ('X-2',200,'On Order')
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES ('X-3',300,'')
Insert OK, 1 rows affected
localhost> UPDATE t0 SET k1 = 300 WHERE k0 = 'X-1'
Update OK, 1 rows affected
localhost> DELETE FROM t0 WHERE k0 = 'X-2'
Delete OK, 1 rows affected
localhost> SELECT * FROM t0 WHERE k0 = 'X-1'
Select OK, 1 rows affected
['X-1', 300]
localhost> EXIT
$ 

In print and play mode, one uses --cat and --play and --from and --to and --space options to print write-ahead-log contents, or to send write-ahead-log contents to the server. Here is an example of a print-and-play-mode tarantool client session:

$ tarantool --cat /home/user1/tarantool_test/work_dir/00000000000000000005.xlog --from 22 --to 26
Insert, lsn: 22, time: 1385327353.345869, len: 33, space: 0, cookie: 127.0.0.1:44787 ['X-1', 100]
Insert, lsn: 23, time: 1385327353.346745, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-2', 200, 8243105135088135759]
Insert, lsn: 24, time: 1385327353.347352, len: 34, space: 0, cookie: 127.0.0.1:44787 ['X-3', 300, '']
Update, lsn: 25, time: 1385327353.348209, len: 42, space: 0, cookie: 127.0.0.1:44787 ['X-1']
Delete, lsn: 26, time: 1385327353.348879, len: 28, space: 0, cookie: 127.0.0.1:44787 ['X-2']
$ 

In replication mode, one connects as a replica, and then writes a binary log to a file.

The tarantar utility program will create new snapshots by reading existing snapshots and write-ahead-log (xlog) files. Thus it differs from SAVE SNAPSHOT, which creates new snapshots from the database. Since tarantar uses less memory than SAVE SNAPSHOT, it is especially appropriate for taking periodic snapshots as a background task.

To prepare: ensure that the configuration file is available.

To run:

 tarantar [options] configuration-file

where possible options are:

Example:

$ ~/tarantool/client/tarantar/tarantar -c -i 30 ./tarantool.cfg
snap_dir: /home/user/tarantool_test/work_dir
wal_dir:  /home/user/tarantool_test/work_dir
spaces:   1
interval: 30
memory_limit: 0M

START SNAPSHOTTING Fri Oct 25 09:35:25 2013

last snapshot lsn: 7
(snapshot) 00000000000000000007.snap 0.000M processed

( >> ) 00000000000000000006.snap 0.000M processed

START SNAPSHOTTING Fri Oct 25 09:35:55 2013

last snapshot lsn: 7
(snapshot) 00000000000000000007.snap 0.000M processed

( >> ) 00000000000000000006.snap 0.000M processed

snapshot exists, skip.

...

Why tarantar?

To recapitulate the idea of a snapshot and a write-ahead log: Tarantool's database is entirely in memory; however, it has a complete and up-to-date on-disk backup. This consists of snapshot files (extension .snap) which are copies of the database as of the time the snapshot was taken, and write-ahead-log files (extension .xlog) which contain records of insert/update/delete operations that are written when the operations occur. If the tarantool_box server goes down and later restarts, it will recover the database by reading the snapshot and then re-applying the write-ahead-log records.

The approach is reliable. But if the snapshot gets old and the number of write-ahead-log records get huge, then recovery would take too long and .xlog files would take too much space. So periodically one should make new snapshots -- if a .snap file is up to date, then the .xlog files are unnecessary and can be archived.

To take a snapshot with the tarantool client, one can say SAVE SNAPSHOT. SAVE SNAPSHOT will copy every tuple from the in-memory database to the .snap file. However, this is not always the ideal method.

Taking snapshots with tarantar, instead of with SAVE SNAPSHOT, can be better because:

For more explanation of tarantar's design see the Tarantool wiki.

The tarancheck utility program will generate and verify “signature files”. A signature file contains, along with basic information that identifies the database, checksums calculated for each index in each space of the database, based on the latest snapshot and all subsequent entries in the write-ahead log. Signature files are useful for ensuring that databases have been saved without error, and for quick comparisons to see whether a database's components have been modified.

The main reason that tarancheck was created was so that users would be able to compare the consistency of two running servers, the master and the replica. By creating a signature file on the master using the master directory, and then copying the signature file to the replica, one will be able to confirm that the replica is not corrupt.

There is one necessary warning. Since either the master or the replica is likely to be active when tarancheck runs, the check can only be applicable for the database as of the last transaction that was run on both the master and the replica. That is why tarancheck displays last_xlog_lsn, which is the log sequence number of the write-ahead log, when it finishes.

To prepare: ensure that the configuration file contains wal_dir and snap_dir clauses. Tarancheck does not assume that wal_dir and snap_dir have default values.

To run:

 tarancheck [options] configuration-file

where possible options are:

Example:

$ ~/tarantool/client/tarantar/tarancheck --generate=x.crc tarantool.cfg
>>> Signature file generation
configured spaces: 1
snap_dir: ./work_dir
wal_dir: ./work_dir
last snapshot lsn: 1
last xlog lsn: 0
(snapshot) 00000000000000000001.snap
(signature) saving x.crc

With tarantool_deploy one can set up so that, during system boot, one or more instances of the tarantool_box server will start. This utility is for use on Red Hat or CentOS where Tarantool was installed using rpm --install.

Technically, tarantool_deploy will place instructions in /etc/init.d which will initiate tarantool_box with appropriate options and with settings that maximize resource usage. The root password is necessary. These options are available, as shown by tarantool_deploy --help:

Tarantool deployment script: add more Tarantool instances.
usage: tarantool_deploy.sh [options] <instance>

  --prefix <path>       installation path (/usr)
  --prefix_etc <path>   installation etc path (/etc)
  --prefix_var <path>   installation var path (/var)

  --status              display deployment status
  --dry                 don't create anything, show commands

  --debug               show commands
  --yes                 don't prompt
  --help                display this usage

The default prefixes (/usr and /etc and /var) are appropriate if a Tarantool installation was done with default settings, for example tarantool_box should be in /usr/bin. The only necessary argument is the "instance", which is an arbitrary numeric identification formatted as digit.digit. The following is a sample run:

$ tarantool_deploy.sh 0.1
tarantool_deploy.sh: About to deploy Tarantool instance 0.1.
tarantool_deploy.sh: Continue? [n/y]
y
tarantool_deploy.sh: >>> deploy instance 0.1
tarantool_deploy.sh: >>> updating deployment config
tarantool_deploy.sh: done

Tarantool follows the GNU standard for its command line interface: long options start with a double dash (--option), their short counterparts use a single one (-o). For phrases, both dashes and underscores can be used as word separators (--cfg-get and --cfg_get both work). If an option requires an argument, you can either separate it with a space or equals sign (--cfg-get=pid_file and --cfg-get pid_file both work).

The only two options which could affect a running server are:

All advanced configuration parameters must be specified in a configuration file, which is required for server start. If no path to the configuration file is specified on the command line (see --config), the server looks for a file named tarantool.cfg in the current working directory.

To facilitate centralized and automated configuration management, runtime configuration modifications are supported solely through the RELOAD CONFIGURATION administrative statement. Thus, the procedure to change Tarantool configuration at runtime is to edit the configuration file. This ensures that, should the server get killed or restart, no unexpected changes to configuration can occur.

Not all configuration file settings are changeable at runtime: such settings will be highlighted in this reference. If the same setting is given more than once, the latest occurrence takes effect. You can always invoke SHOW CONFIGURATION from the administrative console to show the current configuration.

Tarantool maintains a set of all allowed configuration parameters in two template files, which are easy to maintain and extend: cfg/core_cfg.cfg_tmpl, src/box/box_cfg.cfg_tmpl. These files can always be used as a reference for any parameter in this manual.

In addition, two working examples can be found in the source tree: test/box/tarantool.cfg, test/big/tarantool.cfg.

kostja@shmita:~$ ps -a -o command | grep box
tarantool_box: primary pri: 33013 sec: 33014 adm: 33015

kostja@shmita:~$ ps -a -o command | grep box
tarantool_box: primary@sessions pri: 33013 sec: 33014 adm: 33015

/*
 * Each tuple consists of fields. Three field types are
 * supported.
 */

enum { STR, NUM, NUM64 } field_type;

/*
 * Tarantool is interested in field types only inasmuch as
 * it needs to build indexes on fields. An index
 * can cover one or more fields.
 */

struct index_field_t {
  unsigned int fieldno;
  enum field_type type;
};

/*
 * HASH and TREE and BITSET index types are supported.
 */

enum { HASH, TREE, BITSET } index_type;

struct index_t {
  index_field_t key_field[];
  enum index_type type;
  /* Secondary index may be non-unique */
  bool unique;
};

struct space_t
{
  /* A space can be quickly disabled and re-enabled at run time. */
  bool enabled;
  /*
   * If cardinality is given, each tuple in the space must have exactly
   * this many fields.
   */
  unsigned int cardinality;
  /* estimated_rows is only used for HASH indexes, to preallocate memory. */
  unsigned int estimated_rows;
  struct index_t index[];
};

space[0].enabled = 1
space[0].index[0].type = HASH
space[0].index[0].unique = 1
space[0].index[0].key_field[0].fieldno = 0
space[0].index[0].key_field[0].type = NUM64

space[0] = {
    enabled = 1,
    index = [
        {
            type = HASH,
            key_field = [
                {
                    fieldno = 0,
                    type = NUM64
                }
            ]
        }
    ]
}

The Tarantool API exists so that a client program can send a request packet to the server, and receive a response. Here is an example of a what the client would send for INSERT INTO t0 VALUES ('A','BB'). The BNF description of the components is in file doc/box-protocol.txt. A third-party contribution written in Lua for unpacking Tarantool messages is in file Tnt-dissector.

Now, one could send that packet to the tarantool_box server, and interpret the response (box-protocol.txt has a description of the packet format for responses as well as requests). But it would be easier, and less error-prone, if one could invoke a routine that formats the packet according to typed parameters. Something like response=tarantool_routine("insert",0,"A","B");. And that is why APIs exist for drivers for C, Perl, Python, PHP, Ruby, and so on.

Here is a complete C program that inserts [99999,'BB'] into space[0] via the C API for the binary protocol. To compile, paste the code into a file named example.c and say gcc -o example example.c -I/tarantool-directory/connector/c/include where tarantool-directory = the directory that contains the necessary file tp.h, and the default library path contains the directory where Tarantool library files were placed at installation time. Before trying to run, check that the server (tarantool_box) is running on localhost (127.0.0.1) and its primary port is the default (33013) and space[0]'s primary key type is numeric (space[0].index[0].key_field[0].type = "NUM" in configuration file). To run, say ./example. The program will format a buffer for sending an INSERT request, then open a socket connection with the tarantool_box server at localhost:33013, then send the request, then check if the server returned an error, then — if all is well — print "Insert succeeded". If the row already exists, the program will print “Duplicate key exists in unique index 0”.

#include <arpa/inet.h>
#include <stdio.h>
#include <unistd.h>
#include <tp.h>                                                /* the usual Tarantool include */

int main()
{
  struct tp request;                                           /* area for sending to server */
  struct tp reply;                                             /* area for getting server reply */
  int fd;                                                      /* file descriptor for socket */
  int pk_field_value = 99999;
  struct sockaddr_in tt;                                       /* the usual socket address info */
  tp_init(&request, NULL, 0, tp_realloc, NULL);                /* initialize request buffer */
  tp_insert(&request, 0, 2);                                   /* append INSERT header */
  tp_tuple(&request);                                          /* begin appending body */
  tp_field(&request, (char*) &pk_field_value, 4);              /* append field[0] */
  tp_sz(&request, "BB");                                       /* append field[1] */
  if ((fd = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP)) <= 0)   /* open the socket, abort if failure */
    exit(1);
  memset(&tt, 0, sizeof(tt));                                  /* connect to localhost:33013 */
  tt.sin_family = AF_INET;
  tt.sin_addr.s_addr = inet_addr("127.0.0.1");
  tt.sin_port = htons(33013);
  if (connect(fd, (struct sockaddr *) &tt, sizeof(tt)) < 0)    /* connect, abort if failure */
    exit(1);
  int rc = write(fd, tp_buf(&request), tp_used(&request));     /* send the INSERT request */
  if (rc != tp_used(&request))                                 /* abort if send failed */
    exit(1);
  tp_init(&reply, NULL, 0, tp_realloc, NULL);                  /* initialize reply buffer */
  while (1) {
    ssize_t to_read = tp_req(&reply);
    if (to_read <= 0)
      break;
    ssize_t new_size = tp_ensure(&reply, to_read);
    if (new_size == -1)                                        /* abort if error e.g. no memory */
      exit(1);
    ssize_t res = read(fd, reply.p, to_read);                  /* get reply */
    if (res <= 0)                                              /* abort if error e.g. no reply */
      exit(1);
    tp_use(&reply, res);
  }
  ssize_t server_code = tp_reply(&reply);                      /* display+abort if error e.g. duplicate key */
  if (server_code != 0) {
    printf("error: %-.*s\n", tp_replyerrorlen(&reply),
           tp_replyerror(&reply));
    tp_free(&reply);
    exit(1);
  }
  tp_free(&request);                                           /* clean up */
  tp_free(&reply);
  close(fd);
  printf("Insert succeeded\n");                                /* congratulate self */
  exit(0);
}

The example program only shows one command and does not show all that's necessary for good practice. For that, please see connector/c in the source tree.

Please see https://github.com/tarantool/tarantool-erlang.

Please see http://dgreenru.github.io/tarantool-java/.

Please see http://github.com/devgru/node-tarantool.

The most commonly used Perl driver is DR::Tarantool. It is not supplied as part of the Tarantool repository; it must be installed separately. The most common way to install it is with CPAN, the Comprehensive Perl Archive Network. DR::Tarantool requires other modules which should be installed first. For example, on Ubuntu, the installation could look like this:

sudo cpan install AnyEvent
sudo cpan install Devel::GlobalDestruction
sudo cpan install Coro
sudo cpan install Test::Pod
sudo cpan install Test::Spelling
sudo cpan install PAR::Dist
sudo cpan install DR::Tarantool
      

Here is a complete Perl program that inserts [99999,'BB'] into space[0] via the Perl API. Before trying to run, check that the server (tarantool_box) is running on localhost (127.0.0.1) and its primary port is the default (33013) and space[0]'s primary key type is numeric (space[0].index[0].key_field[0].type = "NUM" in configuration file). To run, paste the code into a file named example.pl and say perl example.pl. The program will connect using an application-specific definition of the space. The program will open a socket connection with the tarantool_box server at localhost:33013, then send an INSERT request, then — if all is well — end without displaying any messages. If tarantool_box is not running on localhost with primary port = 33013, the program will print “Connection refused”.

#!/usr/bin/perl
use DR::Tarantool ':constant', 'tarantool';
use DR::Tarantool ':all';

my $tnt = tarantool
  host    => '127.0.0.1',                      # look for tarantool_box on localhost
  port    => 33013,                            # assume tarantool_box primary port = default
  spaces  => {
    0 => {                                     # definition of space[0] ...
      name => 't0',                            #   space[0] name = 't0'
      default_type => 'STR',                   #   space[0] field type is 'STR' if undefined
      fields => [ {                            #   definition of space[0].fields ...
          name => 'k0', type => 'NUM' } ],     #     space[0].field[0] name='k0',type='NUM'
      indexes => {                             #   definition of space[0] indexes ...
        0 => {
          name => 'k0', fields => 'k0' } } } };

$tnt->insert('t0' => [ 99999, 'BB' ]);         # INSERT INTO t0 VALUES (99999,'BB')
     

The example program only shows one command and does not show all that's necessary for good practice. For that, please see DR::Tarantool CPAN repository.

The PHP driver is tarantool-php. It is not supplied as part of the Tarantool repository; it must be installed separately. It can be installed with git. It requires other modules which should be installed first. For example, on Ubuntu, the installation could look like this:

sudo apt-get install php5-cli
sudo apt-get install php5-dev
sudo apt-get install php-pear
cd ~
git clone https://github.com/tarantool/tarantool-php.git
cd tarantool-php
phpize
./configure
make
make install
    

At this point there is a file named ~/tarantool-php/modules/tarantool.so. PHP will only find it if the PHP initialization file php.ini contains a line like extension=./tarantool.so. So copy tarantool.so to the working directory and tell PHP where to find the php.ini file that contains that line ...

cd ~
cp ./tarantool-php/modules/tarantool.so .
export PHP_INI_SCAN_DIR=~/tarantool-php/test/share
   

Here is a complete PHP program that inserts [99999,'BB'] into space[0] via the PHP API. Before trying to run, check that the server (tarantool_box) is running on localhost (127.0.0.1) and its primary port is the default (33013) and space[0]'s primary key type is numeric (space[0].index[0].key_field[0].type = "NUM" in configuration file). To run, paste the code into a file named example.php and say php example.php. The program will open a socket connection with the tarantool_box server at localhost:33013, then send an INSERT request, then — if all is well — print "Insert succeeded". If the tuple already exists, the program will print “Duplicate key exists in unique index 0”.

<?php
$tarantool = new Tarantool("localhost", 33013, 33015);
try {
  $tarantool->insert(0, array(99999, "BB"), TARANTOOL_FLAGS_ADD);
  print "Insert succeeded\n";
  }
catch (Exception $e) {
  echo "Exception: ", $e->getMessage(), "\n";
  }
?>
    

The example program only shows one command and does not show all that's necessary for good practice. For that, please see tarantool-php project at GitHub.

Here is a complete Python program that inserts [99999,'BB'] into space[0] via the high-level Python API. To prepare, paste the code into a file named example.py and install tarantool-python with either pip install tarantool to install in /usr (requires root privilege) or pip install tarantool --user to install in ~ i.e. user's default directory. Before trying to run, check that the server (tarantool_box) is running on localhost (127.0.0.1) and its primary port is the default (33013) and space[0]'s primary key type is string (space[0].index[0].key_field[0].type = "STR" in configuration file). To run, say python example.py. The program will connect to the server, will send the request, and will not throw an exception if all went well. If the row already exists, the program will throw DatabaseException(“Duplicate key exists in unique index 0”).

#!/usr/bin/python
from tarantool import Connection

c = Connection("127.0.0.1", 33013)
result = c.insert(0,(99999,'BB'))
print result

The example program only shows one command and does not show all that's necessary for good practice. For that, please see http://tarantool-python.readthedocs.org/en/latest/. For an example of a Python API for Queue managers on Tarantool, see https://github.com/tarantool/tarantool-queue-python.

You need Ruby 1.9 or later to use this connector. Connector sources are located in http://github.com/mailru/tarantool-ruby.