Tarantool Rust SDK

Tarantool Rust SDK offers a library for interacting with Tarantool from Rust applications. This document describes the Tarantool API bindings for Rust and includes the following API's:

• Box: spaces, indexes, sequences
• Fibers: fiber attributes, conditional variables, latches, async runtime
• CoIO
• Transactions
• Schema management
• Protocol implementation (net.box): CRUD, stored procedure call, triggers
• Tuple utils
• Logging (see https://docs.rs/log/)
• Error handling

Links:

• Crate page
• API Documentation
• Repository

See also:

• https://tarantool.io
• https://github.com/tarantool/tarantool

Getting Started

The following instructions will help you get a copy of the project up and running on your local machine. For deployment check out the deployment notes at the end of this file.

Prerequisites

• Tarantool 2.10+

Linking issues in macOS

On macOS you may encounter linking errors like this: ld: symbol(s) not found for architecture x86_64. To solve it please put these lines to your $CARGO_HOME/config.toml (~/.cargo/config.toml by default):

[target.x86_64-apple-darwin]
rustflags = [
    "-C", "link-arg=-undefined",  "-C", "link-arg=dynamic_lookup"
]

Usage

Add the following lines to your project's Cargo.toml:

[dependencies]
tarantool = "6.0"

[lib]
crate-type = ["cdylib"]

See https://github.com/picodata/brod for example usage.

Features

• net_box - Enables IPROTO fiber aware client (enabled by default)
• network_client - Enables a second implementation of IPROTO fiber aware client but with Rust async support (enabled by default)
• picodata - Enables support for custom features added in picodata's fork of tarantool
• tokio_components - Enables support for interfacing with tokio based logic through cbus

Stored procedures

There are several ways Tarantool can call a Rust code. It can use either a plugin, a Lua to Rust FFI code generator, or a stored procedure. In this file we only cover the third option, namely Rust stored procedures. Even though Tarantool always treats Rust routines just as "C functions", we keep on using the "stored procedure" term as an agreed convention and also for historical reasons.

This tutorial contains the following simple steps:

1. examples/easy - prints "hello world";
2. examples/harder - decodes a passed parameter value;
3. examples/hardest - uses this library to do a DBMS insert;
4. examples/read - uses this library to do a DBMS select;
5. examples/write - uses this library to do a DBMS replace.

Our examples are a good starting point for users who want to confidently start writing their own stored procedures.

Creating a Cargo project

After getting the prerequisites installed, follow these steps:

1. Create a Cargo project:

$ cargo init --lib

2. Add the following lines to Cargo.toml:

[package]
name = "easy"
version = "0.1.0"
edition = "2018"
# author, license, etc

[dependencies]
tarantool = "6.0"
serde = "1.0"

[lib]
crate-type = ["cdylib"]

3. Create the server entry point named init.lua with the following script:

box.cfg({listen = 3301})
box.schema.func.create('easy', {language = 'C', if_not_exists = true})
box.schema.func.create('easy.easy2', {language = 'C', if_not_exists = true})
box.schema.user.grant('guest', 'execute', 'function', 'easy', {if_not_exists = true})
box.schema.user.grant('guest', 'execute', 'function', 'easy.easy2', {if_not_exists = true})

To learn more about the commands used above, look up their syntax and usage details in the Tarantool documentation:

• box.cfg();
• box.schema.func.create();
• box.schema.user.grant().

4. Edit lib.rs file and add the following lines:

use tarantool::proc;

#[proc]
fn easy() {
    println!("hello world");
}

#[proc]
fn easy2() {
    println!("hello world -- easy2");
}

We are now ready to provide some usage examples. We will show three difficulty levels of calling a function, from a basic usage example (easy), to a couple of more complex shared libraries (harder and hardest) examples. Additionally, there will be separate examples for reading and writing data.

Basic usage example

Compile the application and start the server:

$ cargo build
$ LUA_CPATH=target/debug/lib?.so tarantool init.lua

Check that the generated .so file is on the LUA_CPATH that was specified earlier for the next lines to work.

Although Rust and Lua layout conventions are different, we can take hold of Lua flexibility and fix it by explicitly setting the LUA_CPATH environmental variable, as shown above.

Now you're ready to make some requests. Open separate console window and run Tarantool as a client. Paste the following into the console:

conn = require('net.box').connect(3301)
conn:call('easy')

Again, check out the net.box module documentation if necessary.

The code above establishes a server connection and calls the 'easy' function. Since the easy() function in lib.rs begins with println!("hello world"), the "hello world" string will appear in the server console output.

The code also checks that the call was successful. Since the easy() function in lib.rs ends with return 0, there is no error message to display and the request is over.

Now let's call another function in lib.rs, namely easy2(). The sequence is almost the same as with he easy() function, but there's a difference: if the file name does not match the function name, we have to explicitly specify {file-name}.{function-name}.

conn:call('easy.easy2')

... and this time the result will be hello world -- easy2.

As you can see, calling a Rust function is as straightforward as it can be.

Retrieving call arguments

Create a new crate called "harder". Put these lines to lib.rs:

#[tarantool::proc]
fn harder(fields: Vec<i32>) {
    println!("field_count = {}", fields.len());

    for val in fields {
        println!("val={}", val);
    }
}

The above code defines a stored proc which accepts a sequence of integers.

Compile the program into the harder.so library using cargo build.

Now go back to the client and execute these requests:

box.schema.func.create('harder', {language = 'C'})
box.schema.user.grant('guest', 'execute', 'function', 'harder')
passable_table = {}
table.insert(passable_table, 1)
table.insert(passable_table, 2)
table.insert(passable_table, 3)
capi_connection:call('harder', {passable_table})

This time the call is passing a Lua table (passable_table) to the harder() function. The harder() function will detect it as that was coded in the args part of our example above.

The console output should now look like this:

tarantool> capi_connection:call('harder', {passable_table})
field_count = 3
val=1
val=2
val=3
---
- []
...

As you can see, decoding parameter values passed to a Rust function may be tricky since it requires coding extra routines.

Accessing Tarantool space

Create a new crate called "hardest". Put these lines to lib.rs:

use serde::{Deserialize, Serialize};

use tarantool::{
    proc,
    space::Space,
    tuple::{Encode, Tuple},
};

#[derive(Serialize, Deserialize)]
struct Row {
    pub int_field: i32,
    pub str_field: String,
}

impl Encode for Row {}

#[proc]
fn hardest() -> Tuple {
    let mut space = Space::find("capi_test").unwrap();
    let result = space.insert(&Row {
        int_field: 10000,
        str_field: "String 2".to_string(),
    });
    result.unwrap()
}

This time the Rust function does the following:

1. Finds the capi_test space by calling the Space::find() method;
2. Serializes the row structure to a tuple in auto mode;
3. Inserts the tuple using .insert().

Compile the program into the hardest.so library using cargo build.

Now go back to the client and execute these requests:

box.schema.func.create('hardest', {language = "C"})
box.schema.user.grant('guest', 'execute', 'function', 'hardest')
box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')
capi_connection:call('hardest')

Additionally, execute another request at the client:

box.space.capi_test:select()

The result should look like this:

tarantool> box.space.capi_test:select()
---
- - [10000, 'String 2']
...

The above proves that the hardest() function has succeeded.

Reading example

Create a new crate "read". Put these lines to lib.rs:

use serde::{Deserialize, Serialize};

use tarantool::{
    proc,
    space::Space,
    tuple::Encode,
};

#[derive(Serialize, Deserialize, Debug)]
struct Row {
    pub int_field: i32,
    pub str_field: String,
}

impl Encode for Row {}

#[proc]
fn read() {
    let space = Space::find("capi_test").unwrap();

    let key = 10000;
    let result = space.get(&(key,)).unwrap();
    assert!(result.is_some());

    let result = result.unwrap().decode::<Row>().unwrap();
    println!("value={:?}", result);
}

The above code does the following:

1. Finds the capi_test space by calling Space::find();
2. Formats a search key = 10000 using Rust tuple literal (an alternative to serializing structures);
3. Gets the tuple using .get();
4. Deserializes the result.

Compile the program into the read.so library using cargo build.

Now go back to the client and execute these requests:

box.schema.func.create('read', {language = "C"})
box.schema.user.grant('guest', 'execute', 'function', 'read')
box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')
capi_connection:call('read')

The result of capi_connection:call('read') should look like this:

tarantool> capi_connection:call('read')
uint value=10000.
string value=String 2.
---
- []
...

The above proves that the read() function has succeeded.

Writing example

Create a new crate called "write". Put these lines to lib.rs:

use tarantool::{
    proc,
    error::Error,
    fiber::sleep,
    space::Space,
    transaction::transaction,
};

#[proc]
fn write() -> Result<(i32, String), String> {
    let mut space = Space::find("capi_test")
        .ok_or_else(|| "Can't find space capi_test".to_string())?;

    let row = (1, "22".to_string());

    transaction(|| -> Result<(), Error> {
        space.replace(&row)?;
        Ok(())
    })
    .unwrap();

    sleep(std::time::Duration::from_millis(1));
    Ok(row)
}

The above code does the following:

1. Finds the capi_test space by calling Space::find();
2. Prepares the row value;
3. Launches the transaction;
4. Replaces the tuple in box.space.capi_test
5. Finishes the transaction:
   • performs a commit upon receiving Ok() on closure
   • performs a rollback upon receiving Error();
6. Returns the entire tuple to the caller and lets the caller display it.

Compile the program into the write.so library using cargo build.

Now go back to the client and execute these requests:

box.schema.func.create('write', {language = "C"})
box.schema.user.grant('guest', 'execute', 'function', 'write')
box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')
capi_connection:call('write')

The result of capi_connection:call('write') should look like this:

tarantool> capi_connection:call('write')
---
- [[1, '22']]
...

The above proves that the write() function has succeeded.

As you can see, Rust "stored procedures" have full access to a database.

Cleaning up

• Get rid of each of the function tuples with box.schema.func.drop.
• Get rid of the capi_test space with box.schema.capi_test:drop().
• Remove the *.so files that were created for this tutorial.

Running the tests

To invoke the automated tests run:

make
make test

See test readme for more information about test structure and adding them.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Anton Melnikov
• Dmitriy Koltsov
• Georgy Moshkin
• Egor Ivkov

© 2020-2024 Picodata.io https://git.picodata.io/picodata

License

This project is licensed under the BSD License - see the LICENSE file for details