Crate tarantool_runner

source ·
Expand description


tarantool-runner is a CLI application to execute tarantool-based Rust applications.

In most tarantool Rust-based applications even for smaller utilities we write special running suite because we need tarantool symbols. This project introduces binary tarantool-runner which takes a tarantool-ready shared object like, desired entrypoint name(exported C function) and executes it in the newly created tarantool instance. After execution is completed, tarantool instance is stopped and purged.

Have a quick glance on what a usage of tarantool-runner looks like:

tarantool-runner -p ./target/debug/ -e my_exported_proc -- 'my_input_to_function'

tarantool-runner -p ./target/debug/ -e my_exported_proc -- '{"key": "value"}'

Examples where tarantool-runner shines:

  1. shors module introduces a brilliant feature: it can generate openapi spec directly from routes. But this algorithm involves slight interaction with tarantool-module, so it requires tarantool symbols. Without tarantool-runner, we have to write wrapping script that would execute needed rust binary in the tarantool environment ourselves. Instead, we can simply use tarantool-runner with the needed entrypoint.

  2. Many tarantool projects require unit testing - and even unit testing could not always be executed without tarantool environment. Therefore, from project to project we write functional test suite that launches tarantool environment. tarantool-runner solves this issue partially - it can run any exported function in the tarantool environment, but you still have to use some test boilerplate to absorb and collect tests marked with #[tarantool::test]. If it is your primary case, you’d better use tarantool-test, which includes needed boilerplate and uses tarantool-runner internally, wrapping it in a pretty CLI interface.

Utility installation

You can install binary utility from cargo install tarantool-runner. Or directly from the repository:

git clone
cd tarantool-runner
cargo install tarantool-runner

If you are interested in extending tarantool-runner or writing your own tarantool-oriented CLI application, follow the relevant section.


You can see sample of usage in Makefile: target run-example executes several entrypoints from example application, which can be found in example subdir.

For your own project, your actions are as follows:

  1. Ensure your package’s entrypoints are usable from Lua code - if you are using tarantool-module it must be already done. Most of the time you just need to mark them with tarantool::proc:
pub fn entrypoint_with_input(input: String) -> Result<()> {

  1. Compile your package: cargo build -p mypackage. At this point, take a note what is the path to the resulting shared object. It is often like ./target/debug/ for linux or ./target/debug/libmypackage.dylib for macos;

  2. Use installed utility with the needed parameters and input(goes after --): tarantool-runner run -p ./target/debug/ -e entrypoint_with_input -- '{"input": "can be json or any other format"}'. You are done!

Using as a base for CLI applications

You can also use tarantool-runner as a base for your own CLI application. Just use it as a dependency for your project, it exports needed Cli structure, which is an ordinary clap application. Visit tarantool-test for an example how it may look like - it is built on top of tarantool-runner.



By default, tarantool environment is built this way:

  1. Base directory is created - it is directory with random name at /tmp dir. Base dir creation is done via tempfile. Initializing lua script is copied here;
  2. Tarantool does not occupy any address and port, it listens socket that is placed in the previously created base dir. Therefore, you can freely use any amount of tarantool-runner at the same time - they won’t interfere with each other. In fact, it is tested and debugged via integration tests here;
  3. Tmpdir for tarantool runtime files is created - it is tmp directory inside base directory.
  4. WAL mode set to none - as it would be single-instanced environment, we don’t need it. WAL dir is indeed required - and we set it to previously created tmpdir.
  5. memtx_dir is set to tmpdir.

Special environment variables are available for the script and entrypoints:

  1. TARANTOOL_RUNNER_BASEDIR - points to created base dir;
  2. TARANTOOL_RUNNER_TMPDIR - points to created tmpdir(runtime directory for tarantool);
  3. TARANTOOL_RUNNER_PACKAGE_FULLPATH - a full path to the package being executed, for example: ./target/debug/;
  4. TARANTOOL_RUNNER_PACKAGE_LOCATION - directory where package is located, for example: ./target/debug;
  5. TARANTOOL_RUNNER_PACKAGE_NAME - a stem(filename without extension) of package. So if you have your package full path like this: ./target/debug/, then this variable is set to libexample;
  6. TARANTOOL_RUNNER_PACKAGE_ENTRYPOINT - an entrypoint(exported function name) which is being executed.
  7. TARANTOOL_RUNNER_INPUT - string which goes after -- in the CLI interface. Your entrypoints would receive this string as the first argument, so no needs in retrieving it yourself.


Entrypoints are just exported C functions - they don’t even need to have an input argument if you want to. The result of entrypoint affects the exit code of tarantool instance - if they result in error, the whole command is failed. This could be interesting for test suite executions.

Passing input

Input is propagated to the entrypoints from the command line - pass it after --. It is passed as a string to your entrypoint - you can do whatever you want with it, like deserializing.

Custom tarantool init script

Lua initialization script for tarantool is builtin, but you can overwrite it with the -i argument, for example: tarantool-runner run -p ./target/debug/ -e my_entrypoint -i /path/to/my/lua_init_script.lua -- "my_input"

You have full access to the environment variables exposed by tarantool-runner. See section for details about which are available, or check default_init.lua for an example how to use them.


If you have question, problem or suggestion, feel free to reach me directly at or at telegram.

You can also join Picodata chat at telegram and tag me with your question here as well. We’ll be glad to see you there!


  • An application that tarantool-runner runs(if used as a binary - see README) and exports for reuse.