Creating your first Tarantool database

Example on GitHub: create_db

In this tutorial, you create a Tarantool database, write data to it, and select data from this database.

Prerequisites

Before starting this tutorial:

Install the tt utility.
Install Tarantool.

Note

The tt utility provides the ability to install Tarantool software using the tt install command.

Creating an application

The tt create command can be used to create an application from a predefined or custom template. In this tutorial, the application layout is prepared manually:

Create a tt environment in the current directory using the tt init command.
Inside the instances.enabled directory of the created tt environment, create the create_db directory.
Inside instances.enabled/create_db, create the instances.yml and config.yaml files:
- instances.yml specifies instances to run in the current environment. In this example, there is one instance:
```
instance001: 
```
- config.yaml contains basic instance configuration:
```
groups:  group001:  replicasets:  replicaset001:  instances:  instance001:  iproto:  listen:  - uri: '127.0.0.1:3301' 
```
  The instance in the configuration accepts incoming requests on the 3301 port.

Working with the database

Starting an instance

Start the Tarantool instance from the tt environment directory using tt start:
```
$ tt start create_db 
```

To check the running instance, use the tt status command:

$ tt status create_db INSTANCE STATUS PID MODE CONFIG BOX UPSTREAM create_db:instance001 RUNNING 8685 RW ready running -- 

Connect to the instance with tt connect:
```
$ tt connect create_db:instance001  • Connecting to the instance...  • Connected to create_db:instance001 create_db:instance001> 
```
This command opens an interactive Tarantool console with the create_db:instance001> prompt. Now you can enter requests in the command line.

Creating a space

Create a space named bands:

create_db:instance001> box.schema.space.create('bands') --- - engine: memtx  before_replace: 'function: 0x010229d788'  field_count: 0  is_sync: false  is_local: false  on_replace: 'function: 0x010229d750'  temporary: false  index: []  type: normal  enabled: false  name: bands  id: 512 - created ... 

Format the created space by specifying field names and types:

create_db:instance001> box.space.bands:format({  { name = 'id', type = 'unsigned' },  { name = 'band_name', type = 'string' },  { name = 'year', type = 'unsigned' }  }) --- ... 

Creating indexes

Create the primary index based on the id field:

create_db:instance001> box.space.bands:create_index('primary', { parts = { 'id' } }) --- - unique: true  parts:  - fieldno: 1  sort_order: asc  type: unsigned  exclude_null: false  is_nullable: false  hint: true  id: 0  type: TREE  space_id: 512  name: primary ... 

Create the secondary index based on the band_name field:

create_db:instance001> box.space.bands:create_index('secondary', { parts = { 'band_name' } }) --- - unique: true  parts:  - fieldno: 2  sort_order: asc  type: string  exclude_null: false  is_nullable: false  hint: true  id: 1  type: TREE  space_id: 512  name: secondary ... 

Writing and selecting data

Insert three tuples into the space:

create_db:instance001> box.space.bands:insert { 1, 'Roxette', 1986 } --- - [1, 'Roxette', 1986] ... create_db:instance001> box.space.bands:insert { 2, 'Scorpions', 1965 } --- - [2, 'Scorpions', 1965] ... create_db:instance001> box.space.bands:insert { 3, 'Ace of Base', 1987 } --- - [3, 'Ace of Base', 1987] ... 

Select a tuple using the primary index:

create_db:instance001> box.space.bands:select { 3 } --- - - [3, 'Ace of Base', 1987] ... 

Select tuples using the secondary index:

create_db:instance001> box.space.bands.index.secondary:select{'Scorpions'} --- - - [2, 'Scorpions', 1965] ... 

Version:

Creating your first Tarantool database

Prerequisites

Creating an application

Working with the database

Starting an instance

Creating a space

Creating indexes

Writing and selecting data