Skip to main content

hyprstream_metrics_api/storage/
mod.rs

1//! Storage backend abstraction for SQL database operations.
2//!
3//! The `StorageBackend` trait is the seam between the metrics API (this
4//! crate) and the serving engine (`hyprstream-metrics`, AGPL): consumers link
5//! these types and traits, while the serving process wires in an engine
6//! implementation such as DuckDB.
7
8// tonic::Status is the idiomatic gRPC error type - boxing would break API
9#![allow(clippy::result_large_err)]
10
11pub mod view;
12
13use self::view::{ViewDefinition, ViewMetadata};
14use arrow::array::RecordBatch;
15use arrow::datatypes::{DataType, Schema};
16use async_trait::async_trait;
17use std::collections::HashMap;
18use std::sync::Arc;
19use tonic::Status;
20
21/// Credentials for database authentication
22#[derive(Debug, Clone, Default)]
23pub struct Credentials {
24    pub username: Option<String>,
25    pub password: Option<String>,
26}
27
28/// Utility functions for SQL operations
29pub struct StorageUtils;
30
31impl StorageUtils {
32    /// Generate SQL for creating a table with the given schema
33    pub fn generate_create_table_sql(table_name: &str, schema: &Schema) -> Result<String, Status> {
34        let mut sql = format!("CREATE TABLE IF NOT EXISTS {table_name} (");
35        let mut first = true;
36
37        for field in schema.fields() {
38            if !first {
39                sql.push_str(", ");
40            }
41            first = false;
42
43            sql.push_str(&format!(
44                "{} {}",
45                field.name(),
46                match field.data_type() {
47                    DataType::Int64 => "BIGINT",
48                    DataType::Float64 => "DOUBLE PRECISION",
49                    DataType::Utf8 => "VARCHAR",
50                    DataType::Binary => "BLOB",
51                    _ =>
52                        return Err(Status::invalid_argument(format!(
53                            "Unsupported data type: {:?}",
54                            field.data_type()
55                        ))),
56                }
57            ));
58        }
59
60        sql.push(')');
61        Ok(sql)
62    }
63
64    /// Generate SQL for inserting data into a table
65    pub fn generate_insert_sql(table_name: &str, column_count: usize) -> String {
66        let placeholders = vec!["?"; column_count].join(", ");
67        format!("INSERT INTO {table_name} VALUES ({placeholders})")
68    }
69
70    /// Generate SQL for selecting data from a table
71    pub fn generate_select_sql(table_name: &str, projection: Option<Vec<String>>) -> String {
72        let columns = projection
73            .map(|cols| cols.join(", "))
74            .unwrap_or_else(|| "*".to_owned());
75        format!("SELECT {columns} FROM {table_name}")
76    }
77
78    /// Generate SQL for creating a view
79    pub fn generate_view_sql(name: &str, definition: &ViewDefinition) -> String {
80        format!("CREATE VIEW {} AS {}", name, definition.to_sql())
81    }
82}
83
84/// Storage backend trait for SQL database operations.
85#[async_trait]
86pub trait StorageBackend: Send + Sync + 'static {
87    /// Initialize the storage backend.
88    async fn init(&self) -> Result<(), Status>;
89
90    /// Prepare a SQL query and return a handle.
91    /// The handle can be used with query_sql to execute the prepared statement.
92    async fn prepare_sql(&self, query: &str) -> Result<Vec<u8>, Status>;
93
94    /// Execute a prepared SQL query using its handle.
95    /// Returns results as an Arrow record batch.
96    async fn query_sql(&self, statement_handle: &[u8]) -> Result<RecordBatch, Status>;
97
98    /// Create a new instance with the given options.
99    fn new_with_options(
100        connection_string: &str,
101        options: &HashMap<String, String>,
102        credentials: Option<&Credentials>,
103    ) -> Result<Self, Status>
104    where
105        Self: Sized;
106
107    /// Create a new table with the given schema
108    async fn create_table(&self, table_name: &str, schema: &Schema) -> Result<(), Status>;
109
110    /// Execute a DDL/administrative statement that produces no rows
111    /// (e.g. `ALTER TABLE ...`). The default routes through prepare/query;
112    /// backends with a dedicated DDL path should override it.
113    async fn execute_ddl(&self, sql: &str) -> Result<(), Status> {
114        let handle = self.prepare_sql(sql).await?;
115        self.query_sql(&handle).await?;
116        Ok(())
117    }
118
119    /// Insert a record batch into a table
120    async fn insert_into_table(&self, table_name: &str, batch: RecordBatch) -> Result<(), Status>;
121
122    /// Create a view with the given definition
123    async fn create_view(&self, name: &str, definition: ViewDefinition) -> Result<(), Status>;
124
125    /// Get view metadata
126    async fn get_view(&self, name: &str) -> Result<ViewMetadata, Status>;
127
128    /// List all views
129    async fn list_views(&self) -> Result<Vec<String>, Status>;
130
131    /// List all tables
132    async fn list_tables(&self) -> Result<Vec<String>, Status>;
133
134    /// Get schema for a table
135    async fn get_table_schema(&self, table_name: &str) -> Result<Arc<Schema>, Status>;
136
137    /// Drop a view
138    async fn drop_view(&self, name: &str) -> Result<(), Status>;
139
140    /// Drop a table
141    async fn drop_table(&self, table_name: &str) -> Result<(), Status>;
142
143    /// Export a table to Parquet format
144    async fn export_to_parquet(
145        &self,
146        table_name: &str,
147        path: &std::path::Path,
148    ) -> Result<(), Status>;
149
150    /// Import a table from Parquet format
151    async fn import_from_parquet(
152        &self,
153        table_name: &str,
154        path: &std::path::Path,
155    ) -> Result<(), Status>;
156}