22 releases (9 stable)
new 6.1.0 | Dec 11, 2024 |
---|---|
6.0.0 | Nov 20, 2024 |
5.1.0 |
|
4.0.1 | Apr 22, 2024 |
0.0.1 | Jan 22, 2017 |
#39 in Database interfaces
3,457 downloads per month
Used in 10 crates
1.5MB
28K
SLoC
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:
See also:
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 protocol implementation (enabled by default)schema
- Enables schema manipulation utils (WIP as of now)
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:
examples/easy
- prints "hello world";examples/harder
- decodes a passed parameter value;examples/hardest
- uses this library to do a DBMS insert;examples/read
- uses this library to do a DBMS select;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:
- Create a Cargo project:
$ cargo init --lib
- 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"]
- 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:
- 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:
- Finds the
capi_test
space by calling theSpace::find()
method; - Serializes the row structure to a tuple in auto mode;
- 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:
- Finds the
capi_test
space by callingSpace::find()
; - Formats a search key = 10000 using Rust tuple literal (an alternative to serializing structures);
- Gets the tuple using
.get()
; - 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:
- Finds the
capi_test
space by callingSpace::find()
; - Prepares the row value;
- Launches the transaction;
- Replaces the tuple in
box.space.capi_test
- Finishes the transaction:
- performs a commit upon receiving
Ok()
on closure - performs a rollback upon receiving
Error()
;
- performs a commit upon receiving
- 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 withbox.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
Dependencies
~4–17MB
~246K SLoC