pub struct Database { /* private fields */ }Expand description
Main database handle
This is the primary interface for interacting with a CQLite database. It coordinates between the storage engine, schema manager, and query engine.
Implementations§
Source§impl Database
impl Database
Sourcepub async fn open(path: &Path, config: Config) -> Result<Self>
pub async fn open(path: &Path, config: Config) -> Result<Self>
Open a database at the given path with the specified configuration
§Arguments
path- The directory path where the database files will be storedconfig- Database configuration options
§Errors
Returns an error if:
- The path cannot be created or accessed
- Database files are corrupted
- Configuration is invalid
§Examples
use cqlite_core::{Database, Config};
use std::path::{Path, PathBuf};
let config = Config::default();
let db = Database::open(Path::new("./data"), config).await?;Sourcepub async fn open_with_discovered_sstables(
storage_path: &Path,
discovered_table_dirs: Vec<PathBuf>,
config: Config,
) -> Result<Self>
pub async fn open_with_discovered_sstables( storage_path: &Path, discovered_table_dirs: Vec<PathBuf>, config: Config, ) -> Result<Self>
Open a database with pre-discovered SSTable table directories
This method is used in the ingestion flow where SSTable discovery has been performed
externally (e.g., via DiscoveryService) and the database should be initialized with
specific SSTable files rather than scanning the storage directory.
§Use Case
This method is designed for the one-shot ingestion workflow:
DiscoveryService::discover()scans external Cassandra data directoriesSchemaManagerparses schema from discovered filesDatabase::open_with_discovered_sstables()creates a queryable database instance
§Arguments
storage_path- The directory path for database runtime files (WAL, manifest, memtable)discovered_table_dirs- Vector of table directory paths from DiscoveryService (e.g.,/var/lib/cassandra/data/keyspace1/table1-abc123)config- Database configuration options
§Errors
Returns an error if:
- The storage path cannot be created or accessed
- Any discovered table directory cannot be read
- Configuration is invalid
- Storage engine or query engine initialization fails
§Feature Gates
This method is only available when the state_machine feature is enabled (default in M2+).
§Examples
use cqlite_core::{Database, Config};
use std::path::{Path, PathBuf};
let config = Config::default();
let storage_path = Path::new("./runtime");
let discovered_dirs = vec![
PathBuf::from("/var/lib/cassandra/data/keyspace1/table1-abc123"),
PathBuf::from("/var/lib/cassandra/data/keyspace1/table2-def456"),
];
let db = Database::open_with_discovered_sstables(
storage_path,
discovered_dirs,
config
).await?;Sourcepub async fn execute(&self, sql: &str) -> Result<QueryResult>
pub async fn execute(&self, sql: &str) -> Result<QueryResult>
Sourcepub async fn execute_streaming(
&self,
sql: &str,
config: StreamingConfig,
) -> Result<QueryResultIterator>
pub async fn execute_streaming( &self, sql: &str, config: StreamingConfig, ) -> Result<QueryResultIterator>
Execute a SQL query with streaming results (Issue #280)
Returns a QueryResultIterator that yields rows incrementally via a bounded
channel, enabling memory-efficient processing of large result sets.
This is the recommended method for exporting large tables, as it avoids materializing all rows in memory at once.
§Arguments
sql- The SQL query to execute (must be a SELECT statement)config- Streaming configuration (buffer size, chunk hints)
§Errors
Returns an error if:
- Query is not a SELECT statement
- SQL syntax is invalid
- Query execution fails
§Examples
let config = StreamingConfig::default();
let mut iter = db.execute_streaming(
"SELECT * FROM large_table",
config
).await?;
while let Some(row_result) = iter.next_async().await {
let row = row_result?;
// Process row incrementally
}Sourcepub async fn explain(&self, sql: &str) -> Result<ExplainResult>
pub async fn explain(&self, sql: &str) -> Result<ExplainResult>
Sourcepub async fn has_schema_for_table(&self, table: &str) -> bool
pub async fn has_schema_for_table(&self, table: &str) -> bool
Check if schema is available for a table
This is a fast boolean check useful for pre-flight validation.
For detailed diagnostic information, use schema_status().
§Examples
let db = Database::open(std::path::Path::new("./data"), Config::default()).await?;
if !db.has_schema_for_table("users").await {
eprintln!("Warning: No schema found for 'users' table");
}Sourcepub async fn schema_status(&self, table: &str) -> SchemaStatus
pub async fn schema_status(&self, table: &str) -> SchemaStatus
Get detailed schema status for debugging
Returns diagnostic information about schema availability including reasons for missing schemas or extraction failures.
§Examples
let db = Database::open(std::path::Path::new("./data"), Config::default()).await?;
match db.schema_status("users").await {
SchemaStatus::Available { .. } => println!("Schema ready"),
SchemaStatus::ExtractionFailed { cause, suggestion, .. } => {
eprintln!("Schema extraction failed: {}", cause);
eprintln!("Suggestion: {}", suggestion);
}
_ => {}
}Sourcepub async fn stats(&self) -> Result<DatabaseStats>
pub async fn stats(&self) -> Result<DatabaseStats>
Get database statistics
Sourcepub async fn shutdown(&self) -> Result<()>
pub async fn shutdown(&self) -> Result<()>
Shutdown the database storage engine without consuming self.
This is useful for language bindings where the Database is wrapped in an Arc and cannot be consumed. The shutdown operation is idempotent.
For consuming close that also drops the Database, use close().