1pub mod gql {
3 pub use gql_parser::*;
4}
5pub mod catalog;
6mod error;
7pub mod graph;
8mod memtable;
9mod parquet;
10mod persistence;
11mod query;
12mod row_index;
13mod rows;
14mod session;
15mod storage;
16mod transaction;
17pub mod types;
18#[cfg(feature = "visualization")]
19pub mod visualization;
20
21pub use datafusion::arrow;
22use datafusion::common::instant::Instant;
23pub use error::{Error, Result};
24use persistence::{Disk, FileGuard};
25pub use query::QueryResult;
26pub use session::{
27 ExecutionResult, Parameter, QueryLimits, Session, SessionState, StatementOutput,
28 StatementResult, TransactionAction, TransactionStatus, Value,
29};
30use std::{
31 collections::{BTreeMap, HashMap},
32 fs,
33 path::{Path, PathBuf},
34 sync::{
35 atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},
36 Arc, Mutex, OnceLock, Weak,
37 },
38};
39use transaction::{PublishedState, StatementTxn};
40
41#[derive(Clone, Debug, Default)]
42pub struct OpenOptions {
43 pub create_if_missing: bool,
45}
46#[derive(Clone, Copy, Debug, PartialEq, Eq)]
48pub struct StorageOptions {
49 pub memtable_max_rows: usize,
50 pub memtable_max_bytes: usize,
51}
52impl Default for StorageOptions {
53 fn default() -> Self {
54 Self {
55 memtable_max_rows: 65_536,
56 memtable_max_bytes: 16 * 1024 * 1024,
57 }
58 }
59}
60#[derive(Debug, Default)]
61struct Metrics {
62 commits: AtomicU64,
63 conflicts: AtomicU64,
64 commit_wait_micros: AtomicU64,
65 recovery_micros: AtomicU64,
66 checkpoint_micros: AtomicU64,
67 checkpoint_busy: AtomicU64,
68}
69#[derive(Clone, Debug, Default)]
70pub struct Statistics {
71 pub commits: u64,
72 pub conflicts: u64,
73 pub commit_wait_micros: u64,
74 pub recovery_micros: u64,
75 pub checkpoint_micros: u64,
76 pub checkpoint_busy: u64,
77 pub log_bytes: u64,
78 pub memtable_rows: usize,
80 pub memtable_bytes: usize,
81 pub sealed_files: usize,
82}
83#[derive(Debug)]
84struct Inner {
85 disk: Option<Disk>,
86 state: Mutex<MainState>,
87 branches: Mutex<MemoryBranches>,
88 branch_cache: Mutex<HashMap<String, (u64, Arc<PublishedState>)>>,
89 active: AtomicUsize,
90 unhealthy: AtomicBool,
91 metrics: Metrics,
92 storage_options: Mutex<StorageOptions>,
93}
94#[derive(Debug)]
95struct MainState {
96 published: Arc<PublishedState>,
97 generation: u64,
98 needs_recovery: bool,
100}
101impl MainState {
102 fn new(published: PublishedState, generation: u64) -> Self {
103 Self {
104 published: Arc::new(published),
105 generation,
106 needs_recovery: false,
107 }
108 }
109}
110#[derive(Debug, Default)]
111struct MemoryBranches {
112 next_id: u64,
113 commits: BTreeMap<u64, StoredBranchCommit>,
114 refs: BTreeMap<String, u64>,
115}
116#[derive(Debug)]
117struct StoredBranchCommit {
118 #[allow(dead_code)]
119 parent: Option<u64>,
120 state: Arc<PublishedState>,
121}
122impl MemoryBranches {
123 fn publish_main(&mut self, state: &PublishedState) -> Result<()> {
124 let parent = self.refs.get("main").copied();
125 if let Some(id) = parent {
126 if self.commits.get(&id).map(|commit| commit.state.commit_seq) == Some(state.commit_seq)
127 {
128 return Ok(());
129 }
130 }
131 let id = self.allocate()?;
132 self.commits.insert(
133 id,
134 StoredBranchCommit {
135 parent,
136 state: Arc::new(state.clone()),
137 },
138 );
139 self.refs.insert("main".into(), id);
140 Ok(())
141 }
142 fn allocate(&mut self) -> Result<u64> {
143 self.next_id = self
144 .next_id
145 .checked_add(1)
146 .ok_or_else(|| Error::InvalidDefinition("commit ids exhausted".into()))?;
147 Ok(self.next_id)
148 }
149}
150#[derive(Clone, Debug, PartialEq, Eq)]
152pub struct Branch {
153 pub name: String,
154 pub commit: u64,
155}
156#[derive(Clone, Debug)]
157pub struct Database {
158 inner: Arc<Inner>,
159}
160impl Default for Database {
161 fn default() -> Self {
162 Self::new()
163 }
164}
165struct RegisteredDatabase {
166 inner: Weak<Inner>,
167 _owner: FileGuard,
168}
169type Registry = Mutex<HashMap<PathBuf, RegisteredDatabase>>;
170static DATABASES: OnceLock<Registry> = OnceLock::new();
171
172impl Drop for Inner {
173 fn drop(&mut self) {
174 if let Some(disk) = &self.disk {
175 let mut registry = DATABASES
176 .get()
177 .unwrap()
178 .lock()
179 .unwrap_or_else(|e| e.into_inner());
180 if registry
181 .get(&disk.directory)
182 .is_some_and(|entry| std::ptr::eq(entry.inner.as_ptr(), self))
183 {
184 registry.remove(&disk.directory);
185 }
186 }
187 }
188}
189
190impl Database {
191 pub fn new() -> Self {
192 Self {
193 inner: Arc::new(Inner {
194 disk: None,
195 state: Mutex::new(MainState::new(PublishedState::initial(), 0)),
196 branches: Mutex::new(MemoryBranches::default()),
197 branch_cache: Mutex::new(HashMap::new()),
198 active: AtomicUsize::new(0),
199 unhealthy: AtomicBool::new(false),
200 metrics: Metrics::default(),
201 storage_options: Mutex::new(StorageOptions::default()),
202 }),
203 }
204 }
205 pub fn open(path: impl AsRef<Path>, options: OpenOptions) -> Result<Self> {
210 if !cfg!(any(target_os = "linux", target_os = "macos")) {
211 return Err(Error::UnsupportedFeature(
212 "persistent databases require Linux or macOS".into(),
213 ));
214 }
215 let path = path.as_ref();
216 if options.create_if_missing {
217 let existed = path.exists();
218 fs::create_dir_all(path)?;
219 if !existed {
222 let absolute = fs::canonicalize(path)?;
223 for parent in absolute.ancestors().skip(1) {
224 match fs::File::open(parent) {
225 Ok(file) => file.sync_all()?,
226 Err(error) if error.kind() == std::io::ErrorKind::PermissionDenied => {
227 break;
228 }
229 Err(error) => return Err(error.into()),
230 }
231 }
232 }
233 }
234 let directory = fs::canonicalize(path)?;
235 let mut registry = DATABASES
236 .get_or_init(Mutex::default)
237 .lock()
238 .map_err(|_| Error::Poisoned)?;
239 if let Some(inner) = registry
240 .get(&directory)
241 .and_then(|entry| entry.inner.upgrade())
242 {
243 drop(registry);
244 if inner.unhealthy.load(Ordering::SeqCst) {
245 return Err(Error::Poisoned);
246 }
247 return Ok(Self { inner });
248 }
249 registry.remove(&directory);
254 let disk = Disk {
255 directory: directory.clone(),
256 next_commit_id: Mutex::new(None),
257 };
258 let owner = disk.acquire_ownership()?;
259 let _commit = disk.commit_lock()?;
260 if !options.create_if_missing && !directory.join("MANIFEST").exists() {
261 return Err(Error::NotFound("database manifest".into()));
262 }
263 disk.initialize()?;
264 let (state, generation) = disk.load()?;
265 let inner = Arc::new(Inner {
266 disk: Some(disk),
267 state: Mutex::new(MainState::new(state, generation)),
268 branches: Mutex::new(MemoryBranches::default()),
269 branch_cache: Mutex::new(HashMap::new()),
270 active: AtomicUsize::new(0),
271 unhealthy: AtomicBool::new(false),
272 metrics: Metrics::default(),
273 storage_options: Mutex::new(StorageOptions::default()),
274 });
275 registry.insert(
276 directory,
277 RegisteredDatabase {
278 inner: Arc::downgrade(&inner),
279 _owner: owner,
280 },
281 );
282 Ok(Self { inner })
283 }
284 pub fn parse_gql(&self, input: &str) -> gql::Result<gql::Program> {
285 gql::parse(input)
286 }
287 pub fn session(&self) -> Session {
288 Session::new(self.clone())
289 }
290 pub fn create_branch(&self, name: &str) -> Result<u64> {
293 validate_branch_name(name)?;
294 if name == "main" {
295 return Err(Error::AlreadyExists(name.into()));
296 }
297 let mut state = self.inner.state.lock().map_err(|_| Error::Poisoned)?;
298 self.check_healthy()?;
299 self.recover_main(&mut state)?;
300 if let Some(disk) = &self.inner.disk {
301 let _commit = disk.commit_lock()?;
302 if disk.read_ref(name)?.is_some() {
303 return Err(Error::AlreadyExists(name.into()));
304 }
305 let id = disk.ensure_main_snapshot(&state.published)?;
306 disk.write_ref(name, id)?;
307 return Ok(id);
308 }
309 let mut branches = self.inner.branches.lock().map_err(|_| Error::Poisoned)?;
310 if branches.refs.contains_key(name) {
311 return Err(Error::AlreadyExists(name.into()));
312 }
313 branches.publish_main(&state.published)?;
314 let id = *branches
315 .refs
316 .get("main")
317 .ok_or_else(|| Error::Corrupt("main branch snapshot missing".into()))?;
318 branches.refs.insert(name.to_owned(), id);
319 Ok(id)
320 }
321 pub fn branches(&self) -> Result<Vec<Branch>> {
322 let mut listed = if let Some(disk) = &self.inner.disk {
323 let mut state = self.inner.state.lock().map_err(|_| Error::Poisoned)?;
324 self.check_healthy()?;
325 self.recover_main(&mut state)?;
326 let _commit = disk.commit_lock()?;
327 disk.ensure_main_snapshot(&state.published)?;
328 disk.list_refs()?
329 } else {
330 let branches = self.inner.branches.lock().map_err(|_| Error::Poisoned)?;
331 branches
332 .refs
333 .iter()
334 .map(|(name, commit)| (name.clone(), *commit))
335 .collect()
336 };
337 if !listed.iter().any(|(name, _)| name == "main") {
338 listed.push(("main".into(), 0));
339 }
340 listed.sort();
341 Ok(listed
342 .into_iter()
343 .map(|(name, commit)| Branch { name, commit })
344 .collect())
345 }
346 pub(crate) fn read_branch(&self, name: &str) -> Result<(u64, Arc<PublishedState>)> {
347 if let Some(disk) = &self.inner.disk {
348 let id = disk
349 .read_ref(name)?
350 .ok_or_else(|| Error::NotFound(name.into()))?;
351 let mut cache = self
352 .inner
353 .branch_cache
354 .lock()
355 .map_err(|_| Error::Poisoned)?;
356 if let Some((cached_id, state)) = cache.get(name) {
357 if *cached_id == id {
358 return Ok((id, state.clone()));
359 }
360 }
361 let state = Arc::new(disk.read_commit(id)?.state);
362 disk.check_graph_files(&state)?;
363 cache.insert(name.to_owned(), (id, state.clone()));
364 return Ok((id, state));
365 }
366 let branches = self.inner.branches.lock().map_err(|_| Error::Poisoned)?;
367 let id = *branches
368 .refs
369 .get(name)
370 .ok_or_else(|| Error::NotFound(name.into()))?;
371 let state = branches
372 .commits
373 .get(&id)
374 .ok_or_else(|| Error::Corrupt(format!("missing commit {id}")))?
375 .state
376 .clone();
377 Ok((id, state))
378 }
379 pub(crate) fn note_main_commit(&self, state: &PublishedState) -> Result<()> {
380 self.inner
381 .branches
382 .lock()
383 .map_err(|_| Error::Poisoned)?
384 .publish_main(state)
385 }
386 pub(crate) fn publish_branch_commit(
387 &self,
388 name: &str,
389 expected: u64,
390 state: PublishedState,
391 ) -> Result<()> {
392 let mut branches = self.inner.branches.lock().map_err(|_| Error::Poisoned)?;
393 let current = *branches
394 .refs
395 .get(name)
396 .ok_or_else(|| Error::NotFound(name.into()))?;
397 if current != expected {
398 return Err(Error::Conflict("branch moved".into()));
399 }
400 let id = branches.allocate()?;
401 branches.commits.insert(
402 id,
403 StoredBranchCommit {
404 parent: Some(expected),
405 state: Arc::new(state),
406 },
407 );
408 branches.refs.insert(name.to_owned(), id);
409 Ok(())
410 }
411 pub fn with_catalog<T>(
413 &self,
414 inspect: impl FnOnce(&catalog::CatalogSnapshot) -> T,
415 ) -> Result<T> {
416 let tx = StatementTxn::begin(self)?;
417 Ok(inspect(tx.catalog()))
418 }
419 pub fn create_directory(&self, components: &[&str]) -> Result<catalog::ObjectId> {
421 let mut tx = StatementTxn::begin(self)?;
422 let mut parent = catalog::ROOT_DIRECTORY;
423 for name in components {
424 parent = match tx.lookup(parent, catalog::ObjectKind::Directory, name) {
425 Some(entry) => entry.id,
426 None => tx.create(parent, name, catalog::ObjectDefinition::Directory)?,
427 };
428 }
429 tx.commit()?;
430 Ok(parent)
431 }
432 pub fn checkpoint(&self) -> Result<()> {
435 self.check_healthy()?;
436 let started = Instant::now();
437 let mut current = self.inner.state.lock().map_err(|_| Error::Poisoned)?;
438 self.check_healthy()?;
439 if self.inner.active.load(Ordering::SeqCst) != 0 {
440 self.inner
441 .metrics
442 .checkpoint_busy
443 .fetch_add(1, Ordering::Relaxed);
444 return Err(Error::Busy);
445 }
446 self.recover_main(&mut current)?;
447 let _commit = self
448 .inner
449 .disk
450 .as_ref()
451 .map(|d| d.commit_lock())
452 .transpose()?;
453 let mut next = (*current.published).clone();
454 Arc::make_mut(&mut next.storage).reclaim();
455 Arc::make_mut(&mut next.catalog)
456 .names
457 .retain(|_, binding| binding.object.is_some());
458 next.validate()?;
459 if let Some(disk) = &self.inner.disk {
460 let count = next
461 .storage
462 .generations
463 .values()
464 .filter_map(|g| g.parquet.as_ref())
465 .flat_map(|m| m.fragments())
466 .filter(|f| matches!(f, memtable::Fragment::Memory(_)))
467 .count() as u64;
468 let reserved = next
469 .next_id
470 .checked_add(count)
471 .ok_or_else(|| Error::InvalidDefinition("object IDs exhausted".into()))?;
472 current.needs_recovery = true;
473 if count != 0 {
474 if let Err(error) = disk.append(
475 current.generation,
476 &persistence::LogRecord::Reserve { next_id: reserved },
477 ) {
478 if matches!(error, Error::CommitUnknown(_)) {
479 self.inner.unhealthy.store(true, Ordering::SeqCst);
480 }
481 return Err(error);
482 }
483 disk.seal_memtables(&mut next)?;
484 }
485 current.generation = disk.checkpoint(&next, current.generation)?;
486 current.needs_recovery = false;
487 }
488 current.published = Arc::new(next);
489 self.inner
490 .metrics
491 .checkpoint_micros
492 .fetch_add(started.elapsed().as_micros() as u64, Ordering::Relaxed);
493 Ok(())
494 }
495 pub fn configure_storage(&self, options: StorageOptions) -> Result<()> {
498 if options.memtable_max_rows == 0 || options.memtable_max_bytes == 0 {
499 return Err(Error::InvalidDefinition(
500 "MemTable thresholds must be nonzero".into(),
501 ));
502 }
503 *self
504 .inner
505 .storage_options
506 .lock()
507 .map_err(|_| Error::Poisoned)? = options;
508 Ok(())
509 }
510 pub fn statistics(&self) -> Result<Statistics> {
511 let m = &self.inner.metrics;
512 let mut stats = Statistics {
513 commits: m.commits.load(Ordering::Relaxed),
514 conflicts: m.conflicts.load(Ordering::Relaxed),
515 commit_wait_micros: m.commit_wait_micros.load(Ordering::Relaxed),
516 recovery_micros: m.recovery_micros.load(Ordering::Relaxed),
517 checkpoint_micros: m.checkpoint_micros.load(Ordering::Relaxed),
518 checkpoint_busy: m.checkpoint_busy.load(Ordering::Relaxed),
519 log_bytes: 0,
520 memtable_rows: 0,
521 memtable_bytes: 0,
522 sealed_files: 0,
523 };
524 let current = self.inner.state.lock().map_err(|_| Error::Poisoned)?;
525 for manifest in current
526 .published
527 .storage
528 .generations
529 .values()
530 .filter_map(|g| g.parquet.as_ref())
531 {
532 stats.sealed_files += manifest.tables().count();
533 for fragment in manifest.fragments() {
534 if let memtable::Fragment::Memory(t) = fragment {
535 stats.memtable_rows += t
536 .data
537 .batches
538 .iter()
539 .enumerate()
540 .map(|(i, b)| b.num_rows() - t.data.deleted.get(i).map_or(0, |d| d.len()))
541 .sum::<usize>();
542 stats.memtable_bytes += t
543 .data
544 .batches
545 .iter()
546 .map(|b| b.get_array_memory_size())
547 .sum::<usize>();
548 }
549 }
550 }
551 drop(current);
552 if let Some(disk) = &self.inner.disk {
553 for entry in fs::read_dir(&disk.directory)? {
554 let entry = entry?;
555 if entry.file_name().to_string_lossy().starts_with("wal-") {
556 match entry.metadata() {
557 Ok(m) => stats.log_bytes += m.len(),
558 Err(e) if e.kind() == std::io::ErrorKind::NotFound => (),
559 Err(e) => return Err(e.into()),
560 }
561 }
562 }
563 }
564 Ok(stats)
565 }
566 fn recover_main(&self, current: &mut MainState) -> Result<()> {
569 if current.needs_recovery {
570 let disk =
571 self.inner.disk.as_ref().ok_or_else(|| {
572 Error::Corrupt("in-memory state requires disk recovery".into())
573 })?;
574 let _commit = disk.commit_lock()?;
575 let started = Instant::now();
576 let (state, generation) = disk.load()?;
577 current.published = Arc::new(state);
578 current.generation = generation;
579 current.needs_recovery = false;
580 self.inner
581 .metrics
582 .recovery_micros
583 .fetch_add(started.elapsed().as_micros() as u64, Ordering::Relaxed);
584 }
585 Ok(())
586 }
587 fn check_healthy(&self) -> Result<()> {
588 if self.inner.unhealthy.load(Ordering::SeqCst) {
589 return Err(Error::Poisoned);
590 }
591 Ok(())
592 }
593}
594
595fn validate_branch_name(name: &str) -> Result<()> {
596 let ok = !name.is_empty()
597 && name != "."
598 && name != ".."
599 && !name.starts_with('.')
600 && name
601 .chars()
602 .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_');
603 if ok {
604 Ok(())
605 } else {
606 Err(Error::InvalidDefinition(format!(
607 "invalid branch name {name}"
608 )))
609 }
610}
611
612#[cfg(test)]
613mod tests;