Getting started with Tarantool 1.6

Evgeniy Shadrin
Apr 26, 2016 · 5 min read

The Tarantool database is well-known in its niche and gains ever greater popularity. I’m also pretty sure there are many enthusiasts who would like to try Tarantool in action. Keeping these users in mind, I’ll bring here a number of simple use cases that would help everyone to get started with this interesting product. As you’ve guessed from the title, the product is Tarantool 1.6.

Install

At Tarantool’s website, you’ll find installation instructions for different operating systems. Here’s an installation script for Ubuntu:

curl http://download.tarantool.org/tarantool/1.6/gpgkey | sudo apt-key add -release=`lsb_release -c -s`sudo rm -f /etc/apt/sources.list.d/*tarantool*.list
sudo tee /etc/apt/sources.list.d/tarantool_1_6.list <<- EOF
deb http://download.tarantool.org/tarantool/1.6/ubuntu/ $release main
deb-src http://download.tarantool.org/tarantool/1.6/ubuntu/ $release main
EOF
sudo apt-get update
sudo apt-get -y install tarantool

Hello world!

Tarantool uses Lua as the embedded programming language (Lua 5.1 based on LuaJIT 2.1). Lua is easy to learn. For example, see this tutorial for a quick start. Further you can use Tarantool as a Lua interpreter:

$ /usr/bin/tarantool
/usr/bin/tarantool: version 1.6.7–593-gc17fa86
type 'help' for interactive help
tarantool> 2 + 3
— -
- 5

tarantool> print ('Ola lua!')
Ola lua!
— -

You can write any script in Lua to implement your logic. First thing, let’s create a file (init.lua) with a startup script that launches Tarantool and prints ‘Hello world!’.

The database library is named box. We’ll define our startup configuration using box.cfg (in Lua, {…} is a table):

box.cfg {
listen = 3311,
logger = 'tarantool.log',
}

Tarantool will run at port 3311 and write logs into the tarantool.log file.

Next, let’s create a function named hello():

local function hello()
print ('Hello world!')
end
hello()

Now we launch the script and enjoy the following output:

$ tarantool init.lua
Hello world!

Database

Records in Tarantool are stored in spaces, which are containers similar to RDBMS tables.

Let’s create a space named test and a primary index for it (you can as well build a secondary index based on any other fields in a record). We’ll be using a tree to store indexes:

s = box.schema.space.create('test')
p = s:create_index('primary', {type = 'tree', parts = {1, 'NUM'}})

Next, let’s fill the test space with key-number records:

for i = 1, 10 do
s:insert({i, i})
end

In this piece of code, the s object refers to box.space.test. We could alternatively put it as this:

box.space.test:insert({i, i})

By the way, here’s an error you can get when launching Tarantool next time:

$ tarantool init.lua 
Hello world!
main/101/init.lua F> Space 'test' already exists

Tarantool stores all its data in the memory. To persist the data, Tarantool creates snapshots and binary xlog files. The error above occurs at startup, when Tarantool loads the recent data from .snap and .xlog files (by default, stored in Tarantool’s working directory). The test space already exists in the database, so we get the error. If you like, you can delete .snap and .xlog files at every Tarantool startup, or add a check saying whether the space already exists:

s = box.space.test
if not s then
s = box.schema.space.create('test')
p = s:create_index('primary', {type = 'tree', parts = {1, 'NUM'}})
for i = 1, 10 do
s:insert({i, i})
end
end

Now let’s make sure that the running Tarantool instance has saved our data and configuration parameters. For this purpose, Tarantool offers an administration console. The Lua way of including modules, packages and other source code files is using the ‘require’ mechanism:

local console = require('console')
console.listen(127.0.0.1:3312)

After you’ve launched a Tarantool instance, you can connect to the administration console at port 3312 (e.g. using nc/telnet with rlwrap for convenience). Now that you’ve connected, you can work with Tarantool directly. As an example, let’s ask Tarantool to display the data stored in the test space:

$ rlwrap nc 0 3312
Tarantool 1.6.7–593-gc17fa86 (Lua console)
type 'help' for interactive help
box.space.test:select()
— -
- — [1, 1]
— [2, 2]
— [3, 3]
— [4, 4]
— [5, 5]
— [6, 6]
— [7, 7]
— [8, 8]
— [9, 9]
— [10, 10]

box.space.test:get(6)
— -
- [6, 6]

Next, let’s check the current configuration parameters of our Tarantool instance:

box.cfg
— -
- snapshot_count: 6
too_long_threshold: 0.5
slab_alloc_factor: 2
slab_alloc_maximal: 1048576
background: false
logger: tarantool.log
slab_alloc_arena: 1
sophia:
page_size: 131072
threads: 5
node_size: 134217728
memory_limit: 0
listen: ‘3311’
logger_nonblock: true
snap_dir: .
coredump: false
sophia_dir: .
wal_mode: write
slab_alloc_minimal: 64
panic_on_snap_error: true
panic_on_wal_error: true
rows_per_wal: 500000
wal_dir: .
log_level: 5
readahead: 16320
snapshot_period: 0
wal_dir_rescan_delay: 0.1

Moving further, let’s try to modify the data stored in the test space: in records with a key greater than 5, we’ll increment the number value by 10.

To select the required records, we’ll use Tarantool’s box.index library.

for k,v in box.space.test.index.primary:pairs(5, {iterator = box.index.GT}) do
s:update(v[1], {{'=', 2, v[2] + 10}})
end

box.space.index.primary is the primary index of our test space.

pairs() is an iterate function; it returns an iterator (the k variable in the for loop) and a table of values (consisting of the v record set), and takes a key value (5, which is our iteration start point) and an iterator type as arguments.

iterator (in our case, the iterator type is box.index.GT) is an iterator that returns records with keys greater than the specified value (5).

update() is a function that updates records in the database; it takes a record’s key value (v[1]) as an argument, and {‘=’, 2, v[2] + 10} means to set (‘=’) the second value in the record to v[2] + 10.

Using the administration console, let’s check the updated values in our test space:

box.space.test:select()
— -
- — [1, 1]
— [2, 2]
— [3, 3]
— [4, 4]
— [5, 5]
— [6, 16]
— [7, 17]
— [8, 18]
— [9, 19]
— [10, 20]

Here is the resulting source code of our sample Lua script:

-- Sample startup script for Tarantool-- Including all the external modules that we need in this script
-- The good practice is to put this at the beginning of the script file
local console = require('console')
-- Launching the administration console
console.listen('127.0.0.1:3312')
-- Setting up Tarantool’s configuration parameters
box.cfg {
listen = 3311,
logger = 'tarantool.log',
}
local function hello()
print ('Hello world!')
end
-- Invoking the hello() function
hello()
-- Creating a test space and filling it with data if the space doesn’t - -- exist
s = box.space.test
if not s then
s = box.schema.space.create('test')
-- Primary index
p = s:create_index('primary', {type = 'tree', parts = {1, 'NUM'}})
for i = 1, 10 do
s:insert({i, i})
end
end
-- Incrementing values in all records with a primary key greater than 5
for k,v in box.space.test.index.primary:pairs(5, {iterator = box.index.GT}) do
s:update(v[1], {{'=', 2, v[2] + 10}})
end

Of course, you’d need to study Tarantool documentation to fully master Tarantool’s capabilities and nuances. Tarantool is not only a DBMS, but also a Lua application server. For example, there are queues and an http server inside. Yet you’ve already made your first step — you’ve written your first Lua script for Tarantool!

Also, you’re welcome to go to try.tarantool.org and try Tarantool online without the need to install it locally.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade