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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
use std::{
ffi::{CStr, c_void},
os::raw::c_char,
ptr::NonNull,
result::Result as StdResult,
};
use libsqlite3_sys::{
SQLITE_DONE, SQLITE_LOCKED_SHAREDCACHE, SQLITE_MISUSE, SQLITE_ROW, sqlite3, sqlite3_stmt,
};
use super::unlock_notify;
use crate::sqlite::{
DEFAULT_MAX_RETRIES,
error::{PrimaryErrCode, SqliteError},
ffi,
type_info::SqliteDataType,
};
/// Wrapper around a raw SQLite statement handle.
#[derive(Debug)]
pub struct StatementHandle(NonNull<sqlite3_stmt>);
// access to SQLite3 statement handles are safe to send and share between threads
// as long as the `sqlite3_step` call is serialized.
unsafe impl Send for StatementHandle {}
impl StatementHandle {
/// Create a new statement handle wrapper.
pub(super) fn new(ptr: NonNull<sqlite3_stmt>) -> Self {
Self(ptr)
}
/// Return the underlying SQLite database handle for this statement.
pub(super) unsafe fn db_handle(&self) -> *mut sqlite3 {
// O(c) access to the connection handle for this statement handle
// https://sqlite.org/c3ref/db_handle.html
ffi::db_handle(self.0.as_ptr())
}
/// Return the last SQLite error for this statement.
pub(crate) fn last_error(&self) -> SqliteError {
SqliteError::new(unsafe { self.db_handle() })
}
/// Return the number of columns in the result set.
pub(crate) fn column_count(&self) -> usize {
// https://sqlite.org/c3ref/column_count.html
ffi::column_count(self.0.as_ptr()) as usize
}
/// Return the number of changes from the last statement.
pub(crate) fn changes(&self) -> u64 {
// returns the number of changes of the *last* statement; not
// necessarily this statement.
// https://sqlite.org/c3ref/changes.html
unsafe { ffi::changes(self.db_handle()) as u64 }
}
/// Returns `true` if this statement is read-only.
pub(crate) fn is_readonly(&self) -> bool {
ffi::stmt_readonly(self.0.as_ptr())
}
/// Return the name of a result column.
pub(crate) fn column_name(&self, index: usize) -> StdResult<String, SqliteError> {
// https://sqlite.org/c3ref/column_name.html
let name = ffi::column_name(self.0.as_ptr(), index as i32);
if name.is_null() {
return Err(self.last_error());
}
let s = unsafe { CStr::from_ptr(name) };
Ok(s.to_string_lossy().into_owned())
}
/// Return the type information for a result column.
pub(crate) fn column_type_info(&self, index: usize) -> Option<SqliteDataType> {
SqliteDataType::from_code(self.column_type(index))
}
/// Return the declared type for a result column, if available.
pub(crate) fn column_decltype(&self, index: usize) -> Option<SqliteDataType> {
let decl = ffi::column_decltype(self.0.as_ptr(), index as i32);
if decl.is_null() {
// If the Nth column of the result set is an expression or subquery,
// then a NULL pointer is returned.
return None;
}
let decl = unsafe { CStr::from_ptr(decl).to_string_lossy() };
let ty: SqliteDataType = decl.parse().ok()?;
Some(ty)
}
// Number Of SQL Parameters
/// Return the number of bind parameters.
pub(crate) fn bind_parameter_count(&self) -> usize {
// https://www.sqlite.org/c3ref/bind_parameter_count.html
ffi::bind_parameter_count(self.0.as_ptr()) as usize
}
// Name Of A Host Parameter
// NOTE: The first host parameter has an index of 1, not 0.
/// Return the name of a bind parameter, if any.
pub(crate) fn bind_parameter_name(&self, index: usize) -> Option<String> {
// https://www.sqlite.org/c3ref/bind_parameter_name.html
let name = ffi::bind_parameter_name(self.0.as_ptr(), index as i32);
if name.is_null() {
return None;
}
let s = unsafe { CStr::from_ptr(name) };
Some(s.to_string_lossy().into_owned())
}
// Binding Values To Prepared Statements
// https://www.sqlite.org/c3ref/bind_blob.html
/// Bind a blob parameter.
pub(crate) fn bind_blob(&self, index: usize, v: &[u8]) -> StdResult<(), SqliteError> {
ffi::bind_blob64(
self.0.as_ptr(),
index as i32,
v.as_ptr() as *const c_void,
v.len() as u64,
)
}
/// Bind a text parameter.
pub(crate) fn bind_text(&self, index: usize, v: &str) -> StdResult<(), SqliteError> {
ffi::bind_text64(
self.0.as_ptr(),
index as i32,
v.as_ptr() as *const c_char,
v.len() as u64,
)
}
/// Bind a 64-bit integer parameter.
pub(crate) fn bind_int64(&self, index: usize, v: i64) -> StdResult<(), SqliteError> {
ffi::bind_int64(self.0.as_ptr(), index as i32, v)
}
/// Bind a floating-point parameter.
pub(crate) fn bind_double(&self, index: usize, v: f64) -> StdResult<(), SqliteError> {
ffi::bind_double(self.0.as_ptr(), index as i32, v)
}
/// Bind a NULL parameter.
pub(crate) fn bind_null(&self, index: usize) -> StdResult<(), SqliteError> {
ffi::bind_null(self.0.as_ptr(), index as i32)
}
// result values from the query
// https://www.sqlite.org/c3ref/column_blob.html
/// Return the SQLite type code for a result column.
pub(crate) fn column_type(&self, index: usize) -> i32 {
ffi::column_type(self.0.as_ptr(), index as i32)
}
/// Return an integer value from a result column.
pub(crate) fn column_int64(&self, index: usize) -> i64 {
ffi::column_int64(self.0.as_ptr(), index as i32)
}
/// Return a floating-point value from a result column.
pub(crate) fn column_double(&self, index: usize) -> f64 {
ffi::column_double(self.0.as_ptr(), index as i32)
}
/// Return a text pointer from a result column.
pub(crate) fn column_text(&self, index: usize) -> *const u8 {
ffi::column_text(self.0.as_ptr(), index as i32)
}
/// Return a blob pointer from a result column.
pub(crate) fn column_blob(&self, index: usize) -> *const c_void {
ffi::column_blob(self.0.as_ptr(), index as i32)
}
/// Return the number of bytes in a result column.
pub(crate) fn column_bytes(&self, index: usize) -> i32 {
ffi::column_bytes(self.0.as_ptr(), index as i32)
}
/// Clear all bound parameters.
pub(crate) fn clear_bindings(&self) {
ffi::clear_bindings(self.0.as_ptr());
}
/// Reset the statement so it can be re-executed.
pub(crate) fn reset(&self) -> StdResult<(), SqliteError> {
// SAFETY: we have exclusive access to the handle
ffi::reset(self.0.as_ptr())?;
Ok(())
}
/// Step the statement, returning whether a row is available.
pub(crate) fn step(&mut self) -> crate::Result<bool> {
// SAFETY: we have exclusive access to the handle
let mut attempts = 0;
loop {
let rc = ffi::step(self.0.as_ptr()).map_err(crate::Error::from)?;
match rc {
SQLITE_ROW => return Ok(true),
SQLITE_DONE => return Ok(false),
SQLITE_MISUSE => {
return Err(unsafe { SqliteError::new(self.db_handle()) }.into());
}
SQLITE_LOCKED_SHAREDCACHE | libsqlite3_sys::SQLITE_LOCKED => {
// The shared cache is locked by another connection. Wait for unlock
// notification and try again.
if attempts >= DEFAULT_MAX_RETRIES {
return Err(crate::Error::UnlockNotify);
}
attempts += 1;
unlock_notify::wait(unsafe { self.db_handle() }, Some(self.0.as_ptr()))?;
// Need to reset the handle after the unlock
// (https://www.sqlite.org/unlock_notify.html)
loop {
if attempts >= DEFAULT_MAX_RETRIES {
return Err(crate::Error::UnlockNotify);
}
attempts += 1;
match ffi::reset(self.0.as_ptr()) {
Ok(()) => break,
Err(ref e) if e.should_retry() => {
unlock_notify::wait(
unsafe { self.db_handle() },
Some(self.0.as_ptr()),
)?;
continue;
}
Err(e) => return Err(e.into()),
}
}
}
libsqlite3_sys::SQLITE_BUSY => {
// Another connection holds a lock that prevented the step from
// completing. Wait for an unlock notification and retry.
if attempts >= DEFAULT_MAX_RETRIES {
return Err(crate::Error::UnlockNotify);
}
attempts += 1;
unlock_notify::wait(unsafe { self.db_handle() }, Some(self.0.as_ptr()))?;
loop {
if attempts >= DEFAULT_MAX_RETRIES {
return Err(crate::Error::UnlockNotify);
}
attempts += 1;
match ffi::reset(self.0.as_ptr()) {
Ok(()) => break,
Err(ref e) if e.should_retry() => {
unlock_notify::wait(
unsafe { self.db_handle() },
Some(self.0.as_ptr()),
)?;
continue;
}
Err(e) => return Err(e.into()),
}
}
}
_ => return Err(unsafe { SqliteError::new(self.db_handle()) }.into()),
}
}
}
}
impl Drop for StatementHandle {
fn drop(&mut self) {
// SAFETY: we have exclusive access to the `StatementHandle` here
{
// Ensure the statement is reset before finalizing so that
// sqlite3_finalize does not return SQLITE_BUSY.
if let Err(e) = ffi::reset(self.0.as_ptr()) {
tracing::error!("sqlite3_reset before finalize failed: {}", e);
}
// https://sqlite.org/c3ref/finalize.html
match ffi::finalize(self.0.as_ptr()) {
Ok(()) => {}
Err(e) => {
if e.primary == PrimaryErrCode::Misuse {
panic!("Detected sqlite3_finalize misuse.");
} else {
tracing::error!(
db_ptr = ?unsafe { self.db_handle() },
"sqlite3_finalize failed: {}",
e
);
}
}
}
}
}
}