Skip to main content

graphfusion/
lib.rs

1//! GQL catalog, sessions, and DataFusion query execution.
2pub 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    /// Persistent databases require a local filesystem with working file locks and atomic rename.
44    pub create_if_missing: bool,
45}
46/// Limits apply to resident batches in each graph. Either limit triggers sealing.
47#[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    /// Resident main-branch rows and Arrow array bytes in the published snapshot.
79    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    // A failed checkpoint or post-WAL publication can leave disk ahead of this state.
99    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/// A named ref pointing at an immutable catalog commit.
151#[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    /// Opens a database directory exclusively for this process. Reopening the same
206    /// canonical directory shares its coordinator; cloned handles and independent
207    /// sessions may be used on multiple threads. Another process gets DatabaseInUse.
208    /// Network filesystems and inherited handles after fork are unsupported.
209    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            // Persist a newly created directory entry. An existing database does not need
220            // its ancestors opened, so a non-readable parent still allows a reopen.
221            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        // A concurrent last-handle drop can leave a dead Weak while Inner::drop
250        // waits for this mutex. Release its lock here before acquiring a new one;
251        // otherwise this process could spuriously reject its own reopen. That
252        // destructor checks identity so it cannot remove the replacement entry.
253        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    /// Points a new branch at the current `main` snapshot. Later commits on that
291    /// branch write a new immutable snapshot and move only its ref.
292    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    /// Inspects one consistent catalog snapshot, without opening a cross-statement transaction.
412    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    /// Administrative provisioning; schema DDL does not implicitly create directories.
420    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    /// Returns Busy instead of waiting for an active statement or explicit transaction,
433    /// which might belong to this thread. Retry after snapshot leases are released.
434    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    /// Changes the thresholds for all handles sharing this coordinator. A successful
496    /// write seals resident batches when either threshold is reached; checkpoint forces sealing.
497    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    // The lifetime ownership lock excludes other processes, and state serializes all
567    // writers in this process. Reload only when a failed write made the cache uncertain.
568    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;