feat: add global registry

- This ensures only a single instance of a db (with is connection
pools) can exist in the process
- NOTE TO REVIEWERS: The caching behavior will be tested from
the outside once the `database.rs` tests are committed.

Author: pmorris-dev

crates/sqlx-sqlite-conn-mgr/src/lib.rs

@@ -19,7 +19,8 @@
 //!
 //! ## Usage
 //!
-//! ```no_run
+//! // TODO: Remove this ignore once implementation is complete
+//! ```ignore
 //! use sqlx_sqlite_conn_mgr::SqliteDatabase;
 //! use std::sync::Arc;
 //!
@@ -59,13 +60,13 @@
 //! - Global registry caches new database instances (with their pools) and returns existing ones
 //! - WAL mode is enabled lazily only when writes are needed
 //!
-// TODO: Remove these allows once implementation is complete
-#![allow(dead_code)]
+// TODO: Remove this allow once implementation is complete
 #![allow(unused)]
 
 mod config;
 mod database;
 mod error;
+mod registry;
 mod write_guard;
 
 // Re-export public types

crates/sqlx-sqlite-conn-mgr/src/registry.rs

@@ -0,0 +1,141 @@
+//! Global database registry to cache new database instances and return existing ones
+
+use crate::Result;
+use crate::database::SqliteDatabase;
+use std::collections::HashMap;
+use std::future::Future;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex, OnceLock, Weak};
+
+/// Global registry for SQLite databases
+static DATABASE_REGISTRY: OnceLock<Mutex<HashMap<PathBuf, Weak<SqliteDatabase>>>> = OnceLock::new();
+
+fn registry() -> &'static Mutex<HashMap<PathBuf, Weak<SqliteDatabase>>> {
+   DATABASE_REGISTRY.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// Get or open a SQLite database connection
+///
+/// If a database is already connected, returns the cached instance.
+/// Otherwise, calls the provided factory function to create a new connection.
+///
+/// Special case: `:memory:` databases are never cached (each is unique)
+pub async fn get_or_open_database<F, Fut>(path: &Path, factory: F) -> Result<Arc<SqliteDatabase>>
+where
+   F: FnOnce() -> Fut,
+   Fut: Future<Output = Result<SqliteDatabase>>,
+{
+   // Skip registry for in-memory databases - always create new
+   if path.to_str() == Some(":memory:") {
+      let db = factory().await?;
+      return Ok(Arc::new(db));
+   }
+
+   // Canonicalize the path for consistent lookups
+   let canonical_path = canonicalize_path(path)?;
+
+   // Check if database is already cached
+   {
+      let mut registry = registry().lock().unwrap_or_else(|poisoned| {
+         #[cfg(debug_assertions)]
+         eprintln!("Registry mutex was poisoned, recovering");
+         poisoned.into_inner()
+      });
+
+      // Clean up dead weak references
+      registry.retain(|_, weak| weak.strong_count() > 0);
+
+      // Try to get existing database
+      if let Some(weak) = registry.get(&canonical_path) {
+         if let Some(db) = weak.upgrade() {
+            return Ok(db);
+         }
+         // Weak reference exists but dead - will be cleaned up below
+      }
+   }
+
+   // Database not cached, create new instance
+   let db = factory().await?;
+   let arc_db = Arc::new(db);
+
+   // Cache the new database
+   {
+      let mut registry = registry().lock().unwrap_or_else(|poisoned| {
+         #[cfg(debug_assertions)]
+         eprintln!("Registry mutex was poisoned, recovering");
+         poisoned.into_inner()
+      });
+      registry.insert(canonical_path, Arc::downgrade(&arc_db));
+   }
+
+   Ok(arc_db)
+}
+
+/// Helper to canonicalize a database path
+fn canonicalize_path(path: &Path) -> std::io::Result<PathBuf> {
+   match path.canonicalize() {
+      Ok(p) => Ok(p),
+      Err(_) => {
+         // If path doesn't exist, try to canonicalize parent + filename
+         let parent = path.parent().unwrap_or_else(|| Path::new("."));
+         let filename = path
+            .file_name()
+            .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid path"))?;
+         let canonical_parent = parent.canonicalize()?;
+         Ok(canonical_parent.join(filename))
+      }
+   }
+}
+
+/// Remove a database from the cache
+///
+/// Special case: `:memory:` databases are never in the registry
+///
+/// Returns an error if the path cannot be canonicalized
+pub fn uncache_database(path: &Path) -> std::io::Result<()> {
+   // Skip registry for in-memory databases
+   if path.to_str() == Some(":memory:") {
+      return Ok(());
+   }
+
+   // Canonicalize path
+   let canonical_path = canonicalize_path(path)?;
+
+   let mut registry = registry().lock().unwrap_or_else(|poisoned| {
+      #[cfg(debug_assertions)]
+      eprintln!("Registry mutex was poisoned, recovering");
+      poisoned.into_inner()
+   });
+   registry.remove(&canonical_path);
+   Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+   use super::*;
+
+   #[test]
+   fn test_canonicalize_path() {
+      let temp_dir = std::env::temp_dir();
+      let test_path = temp_dir.join("test.db");
+
+      // Test that path is canonicalized to absolute path
+      let canonical = canonicalize_path(&test_path).unwrap();
+      assert!(canonical.is_absolute());
+
+      // Test relative path
+      let relative_path = Path::new("./test_relative.db");
+      let canonical_relative = canonicalize_path(relative_path).unwrap();
+      assert!(canonical_relative.is_absolute());
+   }
+
+   #[test]
+   fn test_canonicalize_nonexistent_path() {
+      let temp_dir = std::env::temp_dir();
+      let nonexistent = temp_dir.join("nonexistent_dir").join("test.db");
+
+      // Should fail if parent directory doesn't exist
+      let result = canonicalize_path(&nonexistent);
+      assert!(result.is_err());
+   }
+}