Starting and stopping instances | Tarantool
Sign in Sign up
Download

Version:

latest (3.x)
Administration Starting and stopping instances

Starting and stopping instances

This section describes how to manage instances in a Tarantool cluster using the tt utility. A cluster can include multiple instances that run different code. A typical example is a cluster application that includes router and storage instances. Particularly, you can perform the following actions:

  • start all instances in a cluster or only specific ones
  • check the status of instances
  • connect to a specific instance
  • stop all instances or only specific ones

To get more context on how the application’s environment might look, refer to Application environment.

Note

In this section, a sharded_cluster application is used to demonstrate how to start, stop, and manage instances in a cluster.

Starting Tarantool instances

Starting instances using the tt utility

The tt utility is the recommended way to start Tarantool instances.

$ tt start sharded_cluster
   • Starting an instance [sharded_cluster:storage-a-001]...
   • Starting an instance [sharded_cluster:storage-a-002]...
   • Starting an instance [sharded_cluster:storage-b-001]...
   • Starting an instance [sharded_cluster:storage-b-002]...
   • Starting an instance [sharded_cluster:router-a-001]...

After the cluster has started and worked for some time, you can find its artifacts in the directories specified in the tt configuration. These are the default locations in the local launch mode:

  • sharded_cluster/var/log/<instance_name>/ – instance logs.
  • sharded_cluster/var/lib/<instance_name>/ – snapshots and write-ahead logs.
  • sharded_cluster/var/run/<instance_name>/ – control sockets and PID files.

In the system launch mode, artifacts are created in these locations:

  • /var/log/tarantool/<instance_name>/
  • /var/lib/tarantool/<instance_name>/
  • /var/run/tarantool/<instance_name>/

Starting an instance using the tarantool command

The tarantool command provides additional options that might be helpful for development purposes. Below is the syntax for starting a Tarantool instance configured in a file:

$ tarantool [OPTION ...] --name INSTANCE_NAME --config CONFIG_FILE_PATH

The command below starts router-a-001 configured in the config.yaml file:

$ tarantool --name router-a-001 --config config.yaml

Basic instance management

Most of the commands described in this section can be called with or without an instance name. Without the instance name, they are executed for all instances defined in instances.yaml.

Checking an instance’s status

To check the status of instances, execute tt status:

$ tt status sharded_cluster
INSTANCE                          STATUS      PID
sharded_cluster:storage-a-001     RUNNING     2023
sharded_cluster:storage-a-002     RUNNING     2026
sharded_cluster:storage-b-001     RUNNING     2020
sharded_cluster:storage-b-002     RUNNING     2021
sharded_cluster:router-a-001      RUNNING     2022

To check the status of a specific instance, you need to specify its name:

$ tt status sharded_cluster:storage-a-001
INSTANCE                          STATUS      PID
sharded_cluster:storage-a-001     RUNNING     2023

Connecting to an instance

To connect to the instance, use the tt connect command:

$ tt connect sharded_cluster:storage-a-001
   • Connecting to the instance...
   • Connected to sharded_cluster:storage-a-001

sharded_cluster:storage-a-001>

In the instance’s console, you can execute commands provided by the box module. For example, box.info can be used to get various information about a running instance:

sharded_cluster:storage-a-001> box.info.ro
---
- false
...

Restarting instances

To restart an instance, use tt restart:

$ tt restart sharded_cluster:storage-a-002

After executing tt restart, you need to confirm this operation:

Confirm restart of 'sharded_cluster:storage-a-002' [y/n]: y
   • The Instance sharded_cluster:storage-a-002 (PID = 2026) has been terminated.
   • Starting an instance [sharded_cluster:storage-a-002]...

Stopping instances

To stop the specific instance, use tt stop as follows:

$ tt stop sharded_cluster:storage-a-002

You can also stop all the instances at once as follows:

$ tt stop sharded_cluster
   • The Instance sharded_cluster:storage-b-001 (PID = 2020) has been terminated.
   • The Instance sharded_cluster:storage-b-002 (PID = 2021) has been terminated.
   • The Instance sharded_cluster:router-a-001 (PID = 2022) has been terminated.
   • The Instance sharded_cluster:storage-a-001 (PID = 2023) has been terminated.
   • can't "stat" the PID file. Error: "stat /home/testuser/myapp/instances.enabled/sharded_cluster/var/run/storage-a-002/tt.pid: no such file or directory"

Note

The error message indicates that storage-a-002 is already not running.

Removing instance artifacts

The tt clean command removes instance artifacts (such as logs or snapshots):

$ tt clean sharded_cluster
   • List of files to delete:

   • /home/testuser/myapp/instances.enabled/sharded_cluster/var/log/storage-a-001/tt.log
   • /home/testuser/myapp/instances.enabled/sharded_cluster/var/lib/storage-a-001/00000000000000001062.snap
   • /home/testuser/myapp/instances.enabled/sharded_cluster/var/lib/storage-a-001/00000000000000001062.xlog
   • ...

Confirm [y/n]:

Enter y and press Enter to confirm removing of artifacts for each instance.

Note

The -f option of the tt clean command can be used to remove the files without confirmation.

Preloading Lua scripts and modules

Tarantool supports loading and running chunks of Lua code before starting instances. To load or run Lua code immediately upon Tarantool startup, specify the TT_PRELOAD environment variable. Its value can be either a path to a Lua script or a Lua module name:

  • To run the Lua script preload_script.lua from the sharded_cluster directory, set TT_PRELOAD as follows:

    $ TT_PRELOAD=preload_script.lua tt start sharded_cluster

    Tarantool runs the preload_script.lua code, waits for it to complete, and then starts instances.

  • To load the preload_module from the sharded_cluster directory, set TT_PRELOAD as follows:

    $ TT_PRELOAD=preload_module tt start sharded_cluster

    Note

    TT_PRELOAD values that end with .lua are considered scripts, so avoid module names with this ending.

To load several scripts or modules, pass them in a single quoted string, separated by semicolons:

$ TT_PRELOAD="preload_script.lua;preload_module" tt start sharded_cluster

If an error happens during the execution of the preload script or module, Tarantool reports the problem and exits.

tarantool command-line options

Options that can be passed when starting a Tarantool instance:

-h, --help

Print an annotated list of all available options and exit.

--help-env-list

Since: 3.0.0.

Show a list of environment variables that can be used to configure Tarantool.

-v, -V, --version

Print the product name and version.

Example

$ tarantool --version
Tarantool Enterprise 3.0.0-beta1-2-gcbb569b4c-r607-gc64
Target: Linux-x86_64-RelWithDebInfo
...

In this example:

  • 3.0.0 is a Tarantool version. Tarantool follows semantic versioning, which is described in the Tarantool release policy section.
  • Target is the platform Tarantool is built on. Platform-specific details may follow this line.
-c, --config PATH

Since: 3.0.0.

Set a path to a YAML configuration file. You can also configure this value using the TT_CONFIG environment variable.

See also: Starting an instance using the tarantool command

-n, --name INSTANCE

Since: 3.0.0.

Set the name of an instance to run. You can also configure this value using the TT_INSTANCE_NAME environment variable.

See also: Starting an instance using the tarantool command

-i

Enter an interactive mode.

Example

$ tarantool -i
-e EXPR

Execute the ‘EXPR’ string. See also: lua man page.

Example

$ tarantool -e 'print("Hello, world!")'
Hello, world!
-l NAME

Require the ‘NAME’ library. See also: lua man page.

Example

$ tarantool -l luatest.coverage script.lua
-j cmd

Perform a LuaJIT control command. See also: Command Line Options.

Example

$ tarantool -j off app.lua
-b ...

Save or list bytecode. See also: Command Line Options.

Example

$ tarantool -b test.lua test.out
-d SCRIPT

Activate a debugging session for ‘SCRIPT’. See also: luadebug.lua.

Example

$ tarantool -d app.lua
--

Stop handling options. See also: lua man page.

-

Stop handling options and execute the standard input as a file. See also: lua man page.

Found what you were looking for?
Feedback
Application environment
Managing modules
Single-page version