duckdb/
config.rs

1use super::{ffi, Result};
2use crate::error::Error;
3use std::{default::Default, ffi::CString, os::raw::c_char, ptr};
4
5use strum::{AsRefStr, Display, EnumString};
6
7/// duckdb access mode, default is Automatic
8#[derive(Debug, Eq, PartialEq, Clone, EnumString, Display, AsRefStr)]
9pub enum AccessMode {
10    /// Access mode of the database AUTOMATIC
11    #[strum(to_string = "AUTOMATIC")]
12    Automatic,
13    /// Access mode of the database READ_ONLY
14    #[strum(to_string = "READ_ONLY")]
15    ReadOnly,
16    /// Access mode of the database READ_WRITE
17    #[strum(to_string = "READ_WRITE")]
18    ReadWrite,
19}
20
21/// duckdb default order, default is Asc
22#[derive(Debug, Eq, PartialEq, Clone, EnumString, Display, AsRefStr)]
23pub enum DefaultOrder {
24    /// The order type, ASC
25    #[strum(to_string = "ASC")]
26    Asc,
27    /// The order type, DESC
28    #[strum(to_string = "DESC")]
29    Desc,
30}
31
32/// duckdb default null order, default is nulls first
33#[derive(Debug, Eq, PartialEq, Clone, EnumString, Display, AsRefStr)]
34pub enum DefaultNullOrder {
35    /// Null ordering, NullsFirst
36    #[strum(to_string = "NULLS_FIRST")]
37    NullsFirst,
38    /// Null ordering, NullsLast
39    #[strum(to_string = "NULLS_LAST")]
40    NullsLast,
41}
42
43/// duckdb configuration
44/// Refer to <https://github.com/duckdb/duckdb/blob/master/src/main/config.cpp>
45#[derive(Default)]
46pub struct Config {
47    config: Option<ffi::duckdb_config>,
48}
49
50impl Config {
51    pub(crate) fn duckdb_config(&self) -> ffi::duckdb_config {
52        self.config.unwrap_or(std::ptr::null_mut() as ffi::duckdb_config)
53    }
54
55    /// enable autoload extensions
56    pub fn enable_autoload_extension(mut self, enabled: bool) -> Result<Self> {
57        let value = (enabled as u8).to_string();
58        self.set("autoinstall_known_extensions", &value)?;
59        self.set("autoload_known_extensions", &value)?;
60        Ok(self)
61    }
62
63    /// Access mode of the database ([AUTOMATIC], READ_ONLY or READ_WRITE)
64    pub fn access_mode(mut self, mode: AccessMode) -> Result<Self> {
65        self.set("access_mode", mode)?;
66        Ok(self)
67    }
68
69    /// Metadata from DuckDB callers
70    pub fn custom_user_agent(mut self, custom_user_agent: &str) -> Result<Self> {
71        self.set("custom_user_agent", custom_user_agent)?;
72        Ok(self)
73    }
74
75    /// The order type used when none is specified ([ASC] or DESC)
76    pub fn default_order(mut self, order: DefaultOrder) -> Result<Self> {
77        self.set("default_order", order)?;
78        Ok(self)
79    }
80
81    /// Null ordering used when none is specified ([NULLS_FIRST] or NULLS_LAST)
82    pub fn default_null_order(mut self, null_order: DefaultNullOrder) -> Result<Self> {
83        self.set("default_null_order", null_order)?;
84        Ok(self)
85    }
86
87    /// Allow the database to access external state (through e.g. COPY TO/FROM, CSV readers, pandas replacement scans, etc)
88    pub fn enable_external_access(mut self, enabled: bool) -> Result<Self> {
89        self.set("enable_external_access", enabled.to_string())?;
90        Ok(self)
91    }
92
93    /// Whether or not object cache is used to cache e.g. Parquet metadata
94    pub fn enable_object_cache(mut self, enabled: bool) -> Result<Self> {
95        self.set("enable_object_cache", enabled.to_string())?;
96        Ok(self)
97    }
98
99    /// Allow to load third-party duckdb extensions.
100    pub fn allow_unsigned_extensions(mut self) -> Result<Self> {
101        self.set("allow_unsigned_extensions", "true")?;
102        Ok(self)
103    }
104
105    /// The maximum memory of the system (e.g. 1GB)
106    pub fn max_memory(mut self, memory: &str) -> Result<Self> {
107        self.set("max_memory", memory)?;
108        Ok(self)
109    }
110
111    /// The number of total threads used by the system
112    pub fn threads(mut self, thread_num: i64) -> Result<Self> {
113        self.set("threads", thread_num.to_string())?;
114        Ok(self)
115    }
116
117    /// Add any setting to the config. DuckDB will return an error if the setting is unknown or otherwise invalid.
118    pub fn with(mut self, key: impl AsRef<str>, value: impl AsRef<str>) -> Result<Self> {
119        self.set(key, value)?;
120        Ok(self)
121    }
122
123    fn set(&mut self, key: impl AsRef<str>, value: impl AsRef<str>) -> Result<()> {
124        let key = key.as_ref();
125        let value = value.as_ref();
126        if self.config.is_none() {
127            let mut config: ffi::duckdb_config = ptr::null_mut();
128            let state = unsafe { ffi::duckdb_create_config(&mut config) };
129            assert_eq!(state, ffi::DuckDBSuccess);
130            self.config = Some(config);
131        }
132        let c_key = CString::new(key).unwrap();
133        let c_value = CString::new(value).unwrap();
134        let state = unsafe {
135            ffi::duckdb_set_config(
136                self.config.unwrap(),
137                c_key.as_ptr() as *const c_char,
138                c_value.as_ptr() as *const c_char,
139            )
140        };
141        if state != ffi::DuckDBSuccess {
142            return Err(Error::DuckDBFailure(
143                ffi::Error::new(state),
144                Some(format!("set {key}:{value} error")),
145            ));
146        }
147        Ok(())
148    }
149}
150
151impl Drop for Config {
152    fn drop(&mut self) {
153        if self.config.is_some() {
154            unsafe { ffi::duckdb_destroy_config(&mut self.config.unwrap()) };
155        }
156    }
157}
158
159#[cfg(test)]
160mod test {
161    use crate::{types::Value, Config, Connection, Result};
162
163    #[test]
164    fn test_default_config() -> Result<()> {
165        let config = Config::default();
166        let db = Connection::open_in_memory_with_flags(config)?;
167        db.execute_batch("CREATE TABLE foo(x Text)")?;
168
169        let mut stmt = db.prepare("INSERT INTO foo(x) VALUES (?)")?;
170        stmt.execute([&"a"])?;
171        stmt.execute([&"b"])?;
172        stmt.execute([&"c"])?;
173        stmt.execute([Value::Null])?;
174
175        let val: Result<Vec<Option<String>>> = db
176            .prepare("SELECT x FROM foo ORDER BY x")?
177            .query_and_then([], |row| row.get(0))?
178            .collect();
179        let val = val?;
180        let mut iter = val.iter();
181        assert_eq!(val.len(), 4);
182        assert_eq!(iter.next().unwrap().as_ref().unwrap(), "a");
183        assert_eq!(iter.next().unwrap().as_ref().unwrap(), "b");
184        assert_eq!(iter.next().unwrap().as_ref().unwrap(), "c");
185        assert!(iter.next().unwrap().is_none());
186        assert_eq!(iter.next(), None);
187
188        Ok(())
189    }
190
191    #[test]
192    fn test_all_config() -> Result<()> {
193        let config = Config::default()
194            .access_mode(crate::AccessMode::ReadWrite)?
195            .default_null_order(crate::DefaultNullOrder::NullsLast)?
196            .default_order(crate::DefaultOrder::Desc)?
197            .enable_external_access(true)?
198            .enable_object_cache(false)?
199            .enable_autoload_extension(true)?
200            .allow_unsigned_extensions()?
201            .custom_user_agent("test_user_agent")?
202            .max_memory("2GB")?
203            .threads(4)?
204            .with("preserve_insertion_order", "true")?;
205
206        let db = Connection::open_in_memory_with_flags(config)?;
207        db.execute_batch("CREATE TABLE foo(x Text)")?;
208
209        let mut stmt = db.prepare("INSERT INTO foo(x) VALUES (?)")?;
210        stmt.execute([&"a"])?;
211        stmt.execute([&"b"])?;
212        stmt.execute([&"c"])?;
213        stmt.execute([Value::Null])?;
214
215        let val: Result<Vec<Option<String>>> = db
216            .prepare("SELECT x FROM foo ORDER BY x")?
217            .query_and_then([], |row| row.get(0))?
218            .collect();
219        let val = val?;
220        let mut iter = val.iter();
221        assert_eq!(iter.next().unwrap().as_ref().unwrap(), "c");
222        assert_eq!(iter.next().unwrap().as_ref().unwrap(), "b");
223        assert_eq!(iter.next().unwrap().as_ref().unwrap(), "a");
224        assert!(iter.next().unwrap().is_none());
225        assert_eq!(iter.next(), None);
226
227        let user_agent: Result<String> = db.query_row("PRAGMA USER_AGENT", [], |row| row.get(0));
228        let user_agent = user_agent.unwrap();
229        assert!(&user_agent.ends_with("rust test_user_agent"));
230
231        Ok(())
232    }
233
234    #[test]
235    fn test_invalid_setting() -> Result<()> {
236        let config = Config::default().with("some-invalid-setting", "true")?;
237        let res = Connection::open_in_memory_with_flags(config);
238        assert_eq!(
239            res.unwrap_err().to_string(),
240            "Invalid Input Error: The following options were not recognized: some-invalid-setting"
241        );
242        Ok(())
243    }
244}
duckdb/config.rs

duckdb/
config.rs
