sql_fun_server_api/
lib.rs

1#![deny(missing_docs)]
2#![doc = include_str!("lib.md")]
3
4mod analyze_query;
5mod collection_management;
6mod describe_table;
7mod initialize_schema;
8mod list_objects;
9
10pub use self::{
11    analyze_query::{
12        AnalyzeQueryArgs, AnalyzeQueryInput, AnalyzeQueryItem, AnalyzeQueryResponse, ColumnAccess,
13        ColumnAccessKind, ParameterDescribe, QueryKind, ResultSetColumn,
14    },
15    collection_management::{
16        Collection, CollectionHandle, ReadCollectionArgs, ReleaseCollectionArgs,
17    },
18    describe_table::{
19        ColumnConstraint, ColumnDefinition, DescribeTableArgs, DescribeTableResponse,
20        TableConstraint,
21    },
22    initialize_schema::{
23        EngineDialect, EngineVersion, ExtensionSpec, InitializeSchemaArgs, SchemaContext,
24    },
25    list_objects::{
26        ListObjectArgs, NameQuery, ObjectKind, ObjectQuery, ObjectSummary, ObjectSummaryField,
27        StringPred,
28    },
29};
30
31use std::path::PathBuf;
32
33/// semantic analysis context handle
34#[derive(serde::Serialize, serde::Deserialize)]
35#[serde(transparent)]
36pub struct ContextHandle(String);
37
38/// position in SQL text
39#[derive(serde::Serialize, serde::Deserialize, derive_getters::Getters)]
40pub struct TextPosition {
41    /// seek offset from file start
42    offset: usize,
43
44    /// line number
45    line: u32,
46
47    /// column number
48    col: u32,
49}
50
51#[cfg(test)]
52mod test_text_position {
53    use testresult::TestResult;
54
55    use crate::TextPosition;
56
57    #[test]
58    fn test_serialize() -> TestResult {
59        let item = TextPosition {
60            offset: 0,
61            line: 1,
62            col: 2,
63        };
64        let json_string = serde_json::to_string(&item)?;
65        assert_eq!(&json_string, r#"{"offset":0,"line":1,"col":2}"#);
66        Ok(())
67    }
68}
69
70/// span in SQL text
71#[derive(serde::Serialize, serde::Deserialize, derive_getters::Getters)]
72pub struct TextSpan {
73    /// span start position
74    from: TextPosition,
75
76    /// span end position
77    to: TextPosition,
78}
79
80/// semantic analysis probrem
81#[derive(serde::Serialize, serde::Deserialize, derive_getters::Getters)]
82pub struct AnalysisProbrem {
83    /// error code
84    code: String,
85
86    /// file path
87    file_path: PathBuf,
88
89    /// statement span
90    statement_span: TextSpan,
91
92    /// probrem span
93    probrem_span: TextSpan,
94}
95
96/// error for api
97#[derive(thiserror::Error, Debug, serde::Serialize, serde::Deserialize)]
98pub enum SqlFunServerApiError {
99    /// require release collection
100    ///
101    /// server keeping to many collections for client, release collection for new listing/analyse request.
102    #[error("require release collection {0:?}")]
103    RequireReleseCollection(Vec<CollectionHandle>),
104}
105
106/// database type reference
107#[derive(serde::Serialize, serde::Deserialize, derive_getters::Getters)]
108pub struct TypeReference {
109    /// schema name
110    schema_name: String,
111    /// local name
112    local_name: String,
113}
114
115/// nullability
116#[derive(serde::Serialize, serde::Deserialize)]
117pub enum Nullability {
118    /// not null
119    NotNull,
120    /// can be null
121    Nullable,
122    /// unknown
123    Unknown,
124}
125
126/// `sql-fun` Server API functions
127#[async_trait::async_trait]
128pub trait SqlFunServerApi {
129    /// Initialize schema-aware query analysis context
130    async fn initialize_schema_context(
131        &self,
132        args: InitializeSchemaArgs,
133    ) -> Result<SchemaContext, SqlFunServerApiError>;
134
135    /// Read a collection
136    ///
137    /// When server returns multiple items, server keeps scrollable collection,
138    /// [`read_collection`] reads items in collection.
139    ///
140    /// # Return value
141    ///
142    /// returns [Collection<T>], T depends collection item type
143    ///
144    async fn read_collection(
145        &self,
146        args: ReadCollectionArgs,
147    ) -> Result<serde_json::Value, SqlFunServerApiError>;
148
149    /// Release a collection
150    ///
151    /// When server returns collection, server keeps scrollable collection,
152    /// [`release_collection`] release a server side collection.
153    ///
154    async fn release_collection(
155        &self,
156        args: ReleaseCollectionArgs,
157    ) -> Result<(), SqlFunServerApiError>;
158
159    /// analyze query
160    async fn analyze_query(
161        &self,
162        args: AnalyzeQueryArgs,
163    ) -> Result<AnalyzeQueryResponse, SqlFunServerApiError>;
164
165    /// list schema objects
166    async fn list_objects(
167        &self,
168        args: ListObjectArgs,
169    ) -> Result<Collection<ObjectSummary>, SqlFunServerApiError>;
170
171    /// describe a table
172    async fn describe_table(
173        &self,
174        args: DescribeTableArgs,
175    ) -> Result<DescribeTableResponse, SqlFunServerApiError>;
176}
sql_fun_server_api/lib.rs

sql_fun_server_api/
lib.rs
