Over a million developers have joined DZone.

Tarantool 101, Guide 1: 10 Steps for Beginners, the Chronically Busy, or the Impatient

DZone's Guide to

Tarantool 101, Guide 1: 10 Steps for Beginners, the Chronically Busy, or the Impatient

This guide covers the very first step of using Tarantool: where to download Tarantool, how to start it up, and a little bit of what you can do with it.

· Database Zone ·
Free Resource

Discover Tarantool's unique features which include powerful stored procedures, SQL support, smart cache, and the speed of 1 million ACID transactions on a single CPU core!

Image title

The in-memory powerhouse Tarantool supports some of the largest and most sophisticated enterprises in the world. But every developer using it had to sit down one day and answer the simple question, “How do I actually get this thing running?” This guide covers that step, i.e. the absolute first one: where to download Tarantool, how to start it up, and a little bit of what you can do with it.

I have based the guide on a Digital Ocean Ubuntu droplet for consistency across platforms, but you could use another cloud service or even a local installation with some tweaks. Also, cutting and pasting doesn’t necessarily encourage learning, but I wanted to point out that if you are in a rush, you could just cut and paste your way to a basic Tarantool HTTP server instance in less than 10 minutes.

In this guide, we will set up a Tarantool server instance that responds to a route parameter that includes a user’s home city and returns that same user’s name with a “hello” message.

Set Up an Empty Server

Let’s begin by signing up for Digital Ocean and creating a basic Ubuntu droplet. Once you're issued an IP address, use SSH to access your instance. If you need help setting up or accessing your droplet, the best guide I can recommend is the beginning of Jason Lengstorf’s post (Digital Ocean also has their own guide).

Install Tarantool

Now let’s proceed to install Tarantool. Copy the entire script from here and paste it into your terminal. Note that you may need to hit “enter” after the last line.

Add a Tarantool Module

After that, we’ll use the Ubuntu package manager to install a module that we’ll need later to run our HTTP server (Tarantool has many add-on modules):

sudo apt-get install tarantool-http

Start the Tarantool Console and Initiate the Database

Next, we’ll start up the Tarantool console, which is similar to the consoles of other databases:


Then, we’ll initiate Tarantool’s database server (referred to as “box”):


Note that box.cfg{} also reloads into RAM any data that was persisted onto disk (we didn’t have any data in our case).

Create Your First Space and Two Indexes

In Tarantool, “spaces” are the equivalent of tables. Let’s set up our first space:


A space’s structure requires that it include at least one primary index, so we’ll add that next:

    type = 'hash',
    parts = {1, 'unsigned'}

One of the features that sets Tarantool apart from the simpler key/value stores is its support for secondary indexes, which allow you to search by an element other than the primary key. So let’s set our secondary index on the third element of a tuple, which is the Tarantool equivalent of a “record” (this third element will correspond to a home city in our mock data):

    parts = {3, 'string'} 

(Note that Lua ordering starts with 1 rather than 0, so we use a 3 here.)

Make an API Call to Get Raw Mock Data to Populate the Database

We will make an HTTP call to jsonplaceholder.typicode.com to get the mock data to populate our database. To do this, we will need the HTTP module that we installed earlier:

http_client = require('http.client').new()

Next, we will make the actual call:

httpCallResults = http_client:request('GET','https://jsonplaceholder.typicode.com/users')

The data comes back in JSON so we will need to turn it into a Lua object. To do this, first we require Tarantool’s JSON module (note that this module ships with Tarantool so we don’t need to install it first, like we did with the HTTP module):


Now we “decode” the data and assign it to a variable:

decodedData = json.decode(httpCallResults.body)

Insert the Mock Data Into the Database

Next, we’ll get our first substantial taste of Lua, Tarantool’s language. We’ll use a short for loop to insert the mock data into the correct locations in the database:

for i=1,10,1 do
        i, decodedData[i].name, decodedData[i].address.city

(Note that we know beforehand that the length of a “users” call at jsonplaceholder is 10.)

Now, let’s perform a basic “select all” statement to make sure that the data was looped over properly:


After that, we exit the console:


Write and Execute a Tarantool Application Using a Lua File

Now that we have set up and populated our database, create a small Tarantool application using your favorite text editor (note that we could have set up and populated the database from a file, as well; we just did it in the console for instructional purposes). So the code below will start a server and send data to the front end when called. It includes routes, controllers, and some templating. This is similar to the back ends of other stacks (i.e. MEAN or LAMP), except that our back-end consists of a single tool, not a separate database and back-end language!


function handler(self)
    return self:render({ json = box.space.firstdb:select() })

function hello(self)
    local id = self:stash('id')
    local name = box.space.firstdb.index.secondary:select(id)
    local distill = name[1][2]
    return self:render({ user = distill })

local server = require('http.server').new(nil, 8080)
    { path = '/:id', template = 'Hello, <%= user %>' }, hello)
server:route({ path = '/'}, handler)

Note that each route is associated with a function and any parameters that come in off of the route need to be “stashed.” Save this file as myfile.lua.

Test It Out

Run the file with tarantool myfile.lua.

If you go to youripaddress:8080, you will see the tuples that we downloaded from jsonplaceholder. Choose a town from the tuples and go to the route youripaddress:8080/hometown. Typing youripaddress:8080/Lebsackbury, for example, will yield Hello, Clementina DuBuque, for the user that lives there.

That’s it for now! Hopefully, you can see that Tarantool is an easy database to use. And once you have the basics down, you can start to explore Tarantool’s more powerful capabilities such as relational database acceleration, smart caching, real-time monitoring, and more.

My next guide will show how to manage Tarantool instances and keep them up with tarantoolctl. 

Discover Tarantool's unique features such as powerful stored procedures, SQL support, smart cache, and the speed of 1 million ACID transactions on a single CPU.

database ,tarantool ,tutorial ,mock data ,data management ,lua

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}