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
use std::fmt;
use std::time::Duration;
use surrealdb_core::kvs::config::{AolMode, SnapshotMode, format_duration};
use crate::engine::local::Db;
use crate::{Connect, Error};
impl<R> Connect<Db, R> {
/// Enable MVCC versioning on the datastore.
///
/// Supported by `SurrealKv` and `Mem` engines.
///
/// # Examples
///
/// ```no_run
/// # #[tokio::main]
/// # async fn main() -> surrealdb::Result<()> {
/// use surrealdb::Surreal;
/// use surrealdb::engine::local::SurrealKv;
///
/// let db = Surreal::new::<SurrealKv>("path/to/database-folder").versioned().await?;
/// # Ok(())
/// # }
/// ```
pub fn versioned(mut self) -> Self {
self.address = self.address.map(|mut endpoint| {
endpoint.append_query_param("versioned", "true");
endpoint
});
self
}
/// Set the version retention period.
///
/// Determines how long old versions are kept before being garbage collected.
/// A duration of zero means unlimited retention.
///
/// Supported by `SurrealKv` and `Mem` engines. Requires `versioned()`.
///
/// # Examples
///
/// ```no_run
/// # #[tokio::main]
/// # async fn main() -> surrealdb::Result<()> {
/// use std::time::Duration;
/// use surrealdb::Surreal;
/// use surrealdb::engine::local::SurrealKv;
///
/// let db = Surreal::new::<SurrealKv>("path/to/database-folder")
/// .versioned()
/// .retention(Duration::from_secs(30 * 86400)) // 30 days
/// .await?;
/// # Ok(())
/// # }
/// ```
pub fn retention(mut self, duration: Duration) -> Self {
self.address = self.address.map(|mut endpoint| {
endpoint.append_query_param("retention", &format_duration(duration));
endpoint
});
self
}
/// Set the disk sync mode.
///
/// Controls how and when data is flushed to disk. Supported by `SurrealKv`,
/// `RocksDb`, and `Mem` engines (the `Mem` engine requires a persist path,
/// e.g. `Surreal::new::<Mem>("/tmp/data")` or `connect("mem:///tmp/data")`,
/// for sync to take effect).
///
/// The `mode` argument can be any type that implements `Display`. The
/// canonical type is `SyncMode`:
///
/// - `SyncMode::Never` - leave flushing to the OS (fastest, least durable).
/// - `SyncMode::Every` - sync on every transaction commit (fast, most durable).
/// - `SyncMode::Interval(duration)` - periodic background flushing (fast, less durable).
///
/// # Examples
///
/// ```no_run
/// # #[tokio::main]
/// # async fn main() -> surrealdb::Result<()> {
/// use surrealdb::Surreal;
/// use surrealdb::engine::local::SurrealKv;
/// use surrealdb_core::kvs::config::SyncMode;
///
/// let db = Surreal::new::<SurrealKv>("path/to/database-folder")
/// .sync(SyncMode::Every)
/// .await?;
/// # Ok(())
/// # }
/// ```
///
/// ```no_run
/// # #[tokio::main]
/// # async fn main() -> surrealdb::Result<()> {
/// use std::time::Duration;
/// use surrealdb::Surreal;
/// use surrealdb::engine::local::RocksDb;
/// use surrealdb_core::kvs::config::SyncMode;
///
/// let db = Surreal::new::<RocksDb>("path/to/database-folder")
/// .sync(SyncMode::Interval(Duration::from_millis(200)))
/// .await?;
/// # Ok(())
/// # }
/// ```
pub fn sync(mut self, mode: impl fmt::Display) -> Self {
self.address = self.address.map(|mut endpoint| {
endpoint.append_query_param("sync", &mode.to_string());
endpoint
});
self
}
/// Set the AOL (Append-Only Log) mode for the `Mem` engine.
///
/// Requires a persist path (e.g. `Surreal::new::<Mem>("/tmp/data")` or
/// `connect("mem:///tmp/data")`).
///
/// - `MemAolMode::Never` - never use AOL (default).
/// - `MemAolMode::Sync` - write synchronously to AOL on every commit.
/// - `MemAolMode::Async` - write asynchronously to AOL after commit.
pub fn aol(mut self, mode: AolMode) -> Self {
self.address = self.address.and_then(|mut endpoint| match endpoint.url.scheme() {
"mem" => {
endpoint.append_query_param("aol", &mode.to_string());
Ok(endpoint)
}
scheme => Err(Error::internal(format!(
"The 'aol' option is only supported by the 'mem' engine, not '{scheme}'"
))),
});
self
}
/// Set the snapshot interval for the `Mem` engine.
///
/// Requires a persist path. Periodic snapshots are created at the given interval.
///
/// - `SnapshotMode::Never` - never use snapshots (default).
/// - `SnapshotMode::Interval(duration)` - take snapshots at the given interval.
pub fn snapshot(mut self, mode: SnapshotMode) -> Self {
self.address = self.address.and_then(|mut endpoint| match endpoint.url.scheme() {
"mem" => {
endpoint.append_query_param("snapshot", &mode.to_string());
Ok(endpoint)
}
scheme => Err(Error::internal(format!(
"The 'snapshot' option is only supported by the 'mem' engine, not '{scheme}'"
))),
});
self
}
}