Skip to main content

uqa_storage_sqlite/connection/
identity.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Database identity belongs to the physical pool, independently of its logical sessions.
8
9use std::path::Path;
10use uqa_storage::{PersistentStorageIdentity, StorageBackendError, StorageBackendResult};
11
12use super::{ConnectionSpec, ManagedConnection};
13
14impl ManagedConnection {
15    /// Return the backing database path for a file-backed connection.
16    #[must_use]
17    pub fn database_path(&self) -> Option<&Path> {
18        match &self.pool.spec {
19            ConnectionSpec::File { path, .. }
20            | ConnectionSpec::Auxiliary { path, .. }
21            | ConnectionSpec::Compressed { path, .. } => Some(path),
22            ConnectionSpec::Memory => None,
23        }
24    }
25
26    pub(crate) fn storage_identity(
27        &self,
28    ) -> StorageBackendResult<Option<PersistentStorageIdentity>> {
29        if let Some(path) = self.database_path() {
30            return PersistentStorageIdentity::for_database_path(path).map(Some);
31        }
32        let mut identity = self.pool.memory_identity.lock();
33        if identity.is_none() {
34            let mut bytes = [0_u8; 16];
35            getrandom::fill(&mut bytes).map_err(|error| {
36                StorageBackendError::Other(format!(
37                    "generate SQLite memory database identity: {error}"
38                ))
39            })?;
40            *identity = Some(format!(
41                "uqa-sqlite-memory:{:032x}",
42                u128::from_be_bytes(bytes)
43            ));
44        }
45        Ok(identity.clone().map(PersistentStorageIdentity::Opaque))
46    }
47}
48
49#[cfg(test)]
50mod tests {
51    use super::*;
52
53    #[test]
54    fn memory_database_identity_survives_sessions_and_distinguishes_physical_pools() {
55        let connection = ManagedConnection::open_in_memory().unwrap();
56        let identity = connection.storage_identity().unwrap();
57        assert!(matches!(
58            identity,
59            Some(PersistentStorageIdentity::Opaque(_))
60        ));
61        assert_eq!(connection.clone().storage_identity().unwrap(), identity);
62        assert_eq!(
63            connection.new_session().storage_identity().unwrap(),
64            identity
65        );
66        assert_eq!(
67            connection.record_connection().storage_identity().unwrap(),
68            identity
69        );
70        let sibling = connection.new_session();
71        drop(connection);
72        assert_eq!(sibling.storage_identity().unwrap(), identity);
73        assert_ne!(
74            ManagedConnection::open_in_memory()
75                .unwrap()
76                .storage_identity()
77                .unwrap(),
78            identity
79        );
80    }
81
82    #[test]
83    fn file_database_identity_is_shared_by_independent_pools() {
84        let directory = tempfile::tempdir().unwrap();
85        let path = directory.path().join("identity.db");
86        let first = ManagedConnection::open(&path).unwrap();
87        let second = ManagedConnection::open(&path).unwrap();
88        let expected = Some(PersistentStorageIdentity::for_database_path(&path).unwrap());
89        assert_eq!(first.storage_identity().unwrap(), expected);
90        assert_eq!(second.storage_identity().unwrap(), expected);
91    }
92
93    #[test]
94    fn native_and_key_value_factories_forward_their_memory_database_identity() {
95        use std::sync::Arc;
96        use uqa_storage::PersistentStorageProvider;
97
98        for native in [false, true] {
99            let connection = ManagedConnection::open_in_memory().unwrap();
100            let identity = connection.storage_identity().unwrap();
101            let provider: Arc<dyn PersistentStorageProvider> = if native {
102                Arc::new(crate::SQLiteStorageProvider::new(connection))
103            } else {
104                Arc::new(crate::SQLiteKeyValueStorage::from_connection(connection).unwrap())
105            };
106            assert_eq!(provider.storage_identity().unwrap(), identity);
107            let session = provider.open_session().unwrap();
108            assert_eq!(session.backend.storage_identity().unwrap(), identity);
109            let sibling = session.backend.open_session().unwrap();
110            assert_eq!(sibling.backend.storage_identity().unwrap(), identity);
111            session.backend.begin_read_transaction().unwrap();
112            let retained = session
113                .backend
114                .open_retained_read_session(&uqa_core::CancellationToken::new())
115                .unwrap();
116            assert_eq!(retained.backend.storage_identity().unwrap(), identity);
117            session.backend.rollback_transaction().unwrap();
118        }
119    }
120}