tarantool 5.0.0

Tarantool rust bindings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

#![cfg(any(feature = "picodata", doc))]

use crate::error::TarantoolError;
use crate::ffi;
use crate::ffi::sql::ObufWrapper;
use serde::Serialize;
use std::io::Read;
use std::os::raw::c_char;
use std::str;

/// Returns the hash, used as the statement ID, generated from the SQL query text.
pub fn calculate_hash(sql: &str) -> u32 {
    unsafe { ffi::sql::sql_stmt_calculate_id(sql.as_ptr() as *const c_char, sql.len()) }
}

/// Executes an SQL query without storing the prepared statement in the instance
/// cache and returns a wrapper around the raw msgpack bytes.
pub fn prepare_and_execute_raw<IN>(
    query: &str,
    bind_params: &IN,
    vdbe_max_steps: u64,
) -> crate::Result<impl Read>
where
    IN: Serialize,
{
    let mut buf = ObufWrapper::new(1024);
    // 0x90 is an empty mp array
    let mut param_data = vec![0x90];
    if std::mem::size_of::<IN>() != 0 {
        param_data = rmp_serde::to_vec(bind_params)?;
        debug_assert!(crate::msgpack::skip_value(&mut std::io::Cursor::new(&param_data)).is_ok());
    }
    let param_ptr = param_data.as_ptr() as *const u8;
    let execute_result = unsafe {
        ffi::sql::sql_prepare_and_execute_ext(
            query.as_ptr() as *const u8,
            query.len() as i32,
            param_ptr,
            vdbe_max_steps,
            buf.obuf(),
        )
    };
    if execute_result < 0 {
        return Err(TarantoolError::last().into());
    }
    Ok(buf)
}

/// Creates new SQL prepared statement and stores it in the session.
/// query - SQL query.
///
/// Keep in mind that a prepared statement is stored in the instance cache as
/// long as its reference counter is non-zero. The counter increases only when
/// a new statement is added to a session. Repeatedly calling prepare on an
/// already existing statement within the same session does not increase the
/// instance cache counter. However, calling prepare on the statement in a
/// different session without the statement does increase the counter.

pub fn prepare(query: String) -> crate::Result<Statement> {
    let mut stmt_id: u32 = 0;

    if unsafe {
        ffi::sql::sql_prepare_ext(query.as_ptr(), query.len() as u32, &mut stmt_id as *mut u32)
    } < 0
    {
        return Err(TarantoolError::last().into());
    }

    Ok(Statement { query, id: stmt_id })
}

/// Removes SQL prepared statement from the session.
///
/// The statement is removed from the session, and its reference counter in
/// the instance cache is decremented. If the counter reaches zero, the
/// statement is removed from the instance cache.
pub fn unprepare(stmt: Statement) {
    unsafe {
        ffi::sql::sql_unprepare(stmt.id);
    }
}

/// SQL prepared statement.
#[derive(Default, Debug)]
pub struct Statement {
    query: String,
    id: u32,
}

impl Statement {
    /// Returns original query.
    pub fn source(&self) -> &str {
        self.query.as_str()
    }

    /// Returns the statement ID generated from the SQL query text.
    pub fn id(&self) -> u32 {
        self.id
    }

    /// Executes prepared statement and returns a wrapper over the raw msgpack bytes.
    pub fn execute_raw<IN>(&self, bind_params: &IN, vdbe_max_steps: u64) -> crate::Result<impl Read>
    where
        IN: Serialize,
    {
        let mut buf = ObufWrapper::new(1024);
        // 0x90 is an empty mp array
        let mut param_data = vec![0x90];
        if std::mem::size_of::<IN>() != 0 {
            param_data = rmp_serde::to_vec(bind_params)?;
            debug_assert!(
                crate::msgpack::skip_value(&mut std::io::Cursor::new(&param_data)).is_ok()
            );
        }
        let param_ptr = param_data.as_ptr() as *const u8;
        let execute_result = unsafe {
            ffi::sql::sql_execute_prepared_ext(self.id, param_ptr, vdbe_max_steps, buf.obuf())
        };

        if execute_result < 0 {
            return Err(TarantoolError::last().into());
        }
        Ok(buf)
    }
}