Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

52.3 KB
Raw Blame
use std::collections::{HashMap, HashSet};
use std::future::Future;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, LazyLock, Mutex as StdMutex};
use std::time::{Duration, Instant};

use anyhow::{anyhow, bail, Context, Result};
use chrono_tz::Tz;
use futures::future::poll_fn;
use serde_json::Value;
use taos::{AsyncFetchable, AsyncQueryable, AsyncTBuilder, RawBlock, ResultSet, Taos, TaosBuilder};
use tokio::time::timeout;
use tokio_util::sync::CancellationToken;
use uuid::Uuid;

use crate::config::build_dsn;
use crate::model::{
    AgentConnectionInfo, ColumnInfo, CompletionAssistantCandidate, CompletionAssistantRequest,
    CompletionAssistantResponse, ConnectParams, DatabaseConnectionInfo, DatabaseInfo, MetadataListConstraints,
    ObjectInfo, ObjectSource, QueryOptions, QueryPageResult, QueryResult, TableInfo, DEFAULT_MAX_ROWS,
    TDENGINE_DATA_TYPES,
};
use crate::value::borrowed_value_to_json;

/// 表列表快照的兜底有效期。
///
/// 本进程内执行的可能改变元数据的 SQL 会立刻让快照失效,这里只兜住「其他客户端/其他
/// 实例」造成的元数据变化:最长延迟一分钟能看到新表。大库扫描很贵,不能按每次翻页重扫。
const TABLE_CACHE_TTL: Duration = Duration::from_secs(60);

/// 进程级表快照缓存。
///
/// core 的侧栏翻页会为每次请求新开一个 ephemeral metadata session(随机 session id,
/// 请求结束即关闭,见 `crates/dbx-core/src/schema/mod.rs` 的 `EphemeralAgentMetadataSession`),
/// driver 随该会话创建和销毁,实例级缓存无法跨请求命中。快照因此放到进程级,按
/// 「连接指纹 + 数据库」复用;键里带连接指纹,避免多个连接共用同一 agent 进程时串数据。
static TABLE_SNAPSHOTS: LazyLock<StdMutex<HashMap<String, TableSnapshot>>> = LazyLock::new(Default::default);

/// 元数据代数。
///
/// 任一会话执行 CREATE/DROP/ALTER 等语句后自增,使其他会话里已缓存的快照立即失效,
/// 避免「在 SQL 编辑器里建了表,侧栏却要等 TTL 才看得到」。
static METADATA_GENERATION: AtomicU64 = AtomicU64::new(0);

const QUERY_SESSION_IDLE_TIMEOUT: Duration = Duration::from_secs(10 * 60);
const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);

pub struct TdengineDriver {
    connection: Option<Taos>,
    params: ConnectParams,
    server_version: Option<String>,
    session_timezone: Option<Tz>,
    current_database: String,
    query_sessions: HashMap<String, QueryCursor>,
}

struct TableSnapshot {
    loaded_at: Instant,
    /// 生成该快照时的 `METADATA_GENERATION`,与当前值不一致即视为过期。
    generation: u64,
    /// 共享给所有分页请求,命中缓存时只增加引用计数,不复制整份列表。
    tables: Arc<Vec<TableInfo>>,
}

struct QueryCursor {
    result_set: ResultSet,
    timezone: Option<Tz>,
    session_timezone: Option<Tz>,
    columns: Vec<String>,
    column_types: Vec<String>,
    affected_rows: i64,
    max_rows: usize,
    rows_read: usize,
    pending_block: Option<RawBlock>,
    pending_row_index: usize,
    pending_row: Option<Vec<Value>>,
    last_accessed_at: Instant,
}

impl TdengineDriver {
    pub fn new() -> Self {
        Self {
            connection: None,
            params: ConnectParams::default(),
            server_version: None,
            session_timezone: None,
            current_database: String::new(),
            query_sessions: HashMap::new(),
        }
    }

    pub async fn connect(&mut self, params: ConnectParams) -> Result<()> {
        self.disconnect().await;
        let dsn = build_dsn(&params)?;
        let builder =
            TaosBuilder::from_dsn(&dsn.value).with_context(|| "failed to configure TDengine WebSocket connector")?;
        let connect_timeout = connect_timeout(&params);
        let connection = timeout(connect_timeout, builder.build())
            .await
            .map_err(|_| anyhow!("TDengine connection timed out after {} seconds", connect_timeout.as_secs()))??;
        let token = CancellationToken::new();
        let server_version = query_scalar_string(&connection, "SELECT server_version()", &token, 5).await.ok();
        let session_timezone = query_scalar_string(&connection, "SELECT timezone()", &token, 5)
            .await
            .ok()
            .and_then(|value| parse_server_timezone(&value));
        self.current_database = dsn.database;
        self.server_version = server_version;
        self.session_timezone = session_timezone;
        self.params = params;
        self.connection = Some(connection);
        Ok(())
    }

    pub async fn test_connection(params: ConnectParams) -> Result<DatabaseConnectionInfo> {
        let mut driver = Self::new();
        driver.connect(params).await?;
        let token = CancellationToken::new();
        driver.validate_connection(&token).await?;
        driver.connection_info()?.database_info.ok_or_else(|| anyhow!("TDengine connection metadata is unavailable"))
    }

    pub async fn disconnect(&mut self) {
        self.query_sessions.clear();
        self.server_version = None;
        self.session_timezone = None;
        self.current_database.clear();
        self.connection = None;
    }

    pub async fn validate_connection(&self, token: &CancellationToken) -> Result<()> {
        query_scalar_string(self.require_connection()?, "SELECT server_version()", token, 3).await?;
        Ok(())
    }

    pub fn connection_info(&self) -> Result<AgentConnectionInfo> {
        self.require_connection()?;
        Ok(AgentConnectionInfo {
            identifier_quote: "`".into(),
            compatibility_mode: None,
            database_info: Some(DatabaseConnectionInfo {
                product_name: Some("TDengine".into()),
                product_version: self.server_version.clone(),
                current_database: non_empty(&self.current_database),
                driver_name: Some("taos-connector-rust".into()),
                driver_version: Some("0.12.4-git-f49c3718".into()),
                unquoted_identifier_case: Some("lower"),
                quoted_identifier_case: Some("lower"),
            }),
        })
    }

    pub async fn list_databases(&self, token: &CancellationToken) -> Result<Vec<DatabaseInfo>> {
        let rows = self.query_rows("SHOW DATABASES", token, 0).await?;
        Ok(rows
            .into_iter()
            .filter_map(|row| row.first().and_then(json_text).map(str::to_string))
            .filter(|name| !is_system_database(name))
            .map(|name| DatabaseInfo { name })
            .collect())
    }

    pub fn list_schemas(&self) -> Vec<String> {
        Vec::new()
    }

    pub fn list_data_types(&self) -> Vec<String> {
        TDENGINE_DATA_TYPES.iter().map(|value| (*value).to_string()).collect()
    }

    pub async fn list_tables(
        &mut self,
        database: &str,
        constraints: MetadataListConstraints,
        token: &CancellationToken,
    ) -> Result<Vec<TableInfo>> {
        if !table_type_allowed(&constraints.object_types, "TABLE") {
            return Ok(Vec::new());
        }
        let database = effective_database(database, &self.current_database)?.to_string();
        // 元数据接口的返回顺序没有保证,服务端翻页会让 offset 在两次请求间跳行;
        // 这里始终读取完整列表(进程级快照),在本地排序切片。
        let tables = self.all_tables(&database, token).await?;
        Ok(filter_tables(tables.as_slice(), &constraints))
    }

    pub async fn list_objects(
        &mut self,
        database: &str,
        constraints: MetadataListConstraints,
        token: &CancellationToken,
    ) -> Result<Vec<ObjectInfo>> {
        let database = effective_database(database, &self.current_database)?.to_string();
        let tables = self.list_tables(&database, constraints, token).await?;
        Ok(tables
            .into_iter()
            .map(|table| ObjectInfo {
                name: table.name,
                object_type: table.table_type,
                schema: database.clone(),
                comment: table.comment,
            })
            .collect())
    }

    pub async fn get_columns(&self, database: &str, table: &str, token: &CancellationToken) -> Result<Vec<ColumnInfo>> {
        let database = effective_database(database, &self.current_database)?;
        let rows = self.query_rows(&format!("DESCRIBE {}", qualified_name(database, table)), token, 0).await?;
        Ok(parse_describe_columns(rows))
    }

    pub async fn get_table_comment(&self, _database: &str, _table: &str) -> Result<Option<String>> {
        Ok(None)
    }

    pub async fn get_object_source(
        &self,
        database: &str,
        name: &str,
        object_type: &str,
        token: &CancellationToken,
    ) -> Result<ObjectSource> {
        let database = effective_database(database, &self.current_database)?;
        let mut source = self.get_create_sql(database, name, object_type, token).await?;
        if source.is_empty() {
            let columns = self.get_columns(database, name, token).await?;
            source = build_fallback_table_ddl(database, name, &columns);
        }
        Ok(ObjectSource {
            name: name.to_string(),
            object_type: object_type.to_string(),
            schema: database.to_string(),
            source,
            editable: true,
        })
    }

    pub async fn get_table_ddl(&self, database: &str, table: &str, token: &CancellationToken) -> Result<String> {
        let stable = self.get_create_sql(database, table, "STABLE", token).await?;
        if !stable.is_empty() {
            return Ok(stable);
        }
        let table_source = self.get_create_sql(database, table, "TABLE", token).await?;
        if !table_source.is_empty() {
            return Ok(table_source);
        }
        let columns = self.get_columns(database, table, token).await?;
        Ok(build_fallback_table_ddl(database, table, &columns))
    }

    pub async fn completion_assistant_search(
        &mut self,
        request: CompletionAssistantRequest,
        token: &CancellationToken,
    ) -> Result<CompletionAssistantResponse> {
        let allowed = request.object_kinds.iter().map(|kind| kind.to_ascii_lowercase()).collect::<HashSet<_>>();
        let include_databases = allowed.contains("database") || allowed.contains("schema");
        let include_tables = allowed.is_empty() || allowed.contains("table") || allowed.contains("view");
        let include_columns = allowed.contains("column");
        let max_results = if request.max_results == 0 { 100 } else { request.max_results.min(1000) };
        let mut candidates = Vec::new();
        let requested_database = if !request.parent_schema.trim().is_empty() {
            request.parent_schema.trim()
        } else if !request.schema.trim().is_empty() {
            request.schema.trim()
        } else {
            request.database.trim()
        };
        let databases = if request.global_search || (include_databases && requested_database.is_empty()) {
            self.list_databases(token).await?.into_iter().map(|database| database.name).collect()
        } else {
            vec![effective_database(requested_database, &self.current_database)?.to_string()]
        };

        if include_databases {
            for database in &databases {
                if completion_matches(database, &request) {
                    candidates.push(CompletionAssistantCandidate {
                        name: database.clone(),
                        kind: "schema".into(),
                        database: Some(database.clone()),
                        schema: Some(database.clone()),
                        parent_schema: None,
                        parent_name: None,
                        comment: None,
                        data_type: None,
                    });
                    if candidates.len() >= max_results {
                        return Ok(CompletionAssistantResponse { candidates, incomplete: true, fallback_used: false });
                    }
                }
            }
        }

        for database in databases {
            if include_columns && !request.parent_name.trim().is_empty() {
                for column in self.get_columns(&database, request.parent_name.trim(), token).await? {
                    if completion_matches(&column.name, &request) {
                        candidates.push(CompletionAssistantCandidate {
                            name: column.name,
                            kind: "column".into(),
                            database: Some(database.clone()),
                            schema: Some(database.clone()),
                            parent_schema: Some(database.clone()),
                            parent_name: Some(request.parent_name.trim().to_string()),
                            comment: column.comment,
                            data_type: Some(column.data_type),
                        });
                    }
                    if candidates.len() >= max_results {
                        return Ok(CompletionAssistantResponse { candidates, incomplete: true, fallback_used: false });
                    }
                }
                continue;
            }
            if include_tables {
                let tables = self.all_tables(&database, token).await?;
                for table in tables.iter() {
                    if completion_matches(&table.name, &request) {
                        candidates.push(CompletionAssistantCandidate {
                            name: table.name.clone(),
                            kind: "table".into(),
                            database: Some(database.clone()),
                            schema: Some(database.clone()),
                            parent_schema: None,
                            parent_name: table.parent_name.clone(),
                            comment: table.comment.clone(),
                            data_type: None,
                        });
                    }
                    if candidates.len() >= max_results {
                        return Ok(CompletionAssistantResponse { candidates, incomplete: true, fallback_used: false });
                    }
                }
            }
        }
        Ok(CompletionAssistantResponse { candidates, incomplete: false, fallback_used: false })
    }

    pub async fn execute_query(&mut self, options: QueryOptions, token: &CancellationToken) -> Result<QueryResult> {
        let start = Instant::now();
        self.prepare_database(&options, token).await?;
        let max_rows = normalized_max_rows(options.max_rows);
        let mut cursor = self.start_cursor(&options.sql, max_rows, token, options.timeout_secs).await?;
        let mut page = read_cursor_page(&mut cursor, max_rows, token, options.timeout_secs).await?;
        let (_, truncated) = cursor.prepare_next_page(token, options.timeout_secs).await?;
        page.truncated = truncated;
        if may_change_metadata(&options.sql) {
            invalidate_table_snapshots();
        }
        Ok(QueryResult {
            columns: page.columns,
            column_types: page.column_types,
            rows: page.rows,
            affected_rows: page.affected_rows,
            execution_time_ms: start.elapsed().as_millis() as i64,
            truncated: page.truncated,
        })
    }

    pub async fn execute_query_page(
        &mut self,
        options: QueryOptions,
        token: &CancellationToken,
    ) -> Result<QueryPageResult> {
        let start = Instant::now();
        self.expire_query_sessions();
        self.prepare_database(&options, token).await?;
        let max_rows = normalized_max_rows(options.max_rows);
        let page_size = normalized_page_size(options.page_size, options.fetch_size, max_rows);
        let mut cursor = self.start_cursor(&options.sql, max_rows, token, options.timeout_secs).await?;
        let mut page = read_cursor_page(&mut cursor, page_size, token, options.timeout_secs).await?;
        let (has_more, truncated) = cursor.prepare_next_page(token, options.timeout_secs).await?;
        page.truncated = truncated;
        if has_more {
            let session_id = format!("tdengine-{}", Uuid::new_v4());
            page.session_id = Some(session_id.clone());
            page.has_more = true;
            self.query_sessions.insert(session_id, cursor);
        }
        page.execution_time_ms = start.elapsed().as_millis() as i64;
        if may_change_metadata(&options.sql) {
            invalidate_table_snapshots();
        }
        Ok(page)
    }

    pub async fn fetch_query_page(
        &mut self,
        session_id: &str,
        page_size: usize,
        timeout_secs: u64,
        token: &CancellationToken,
    ) -> Result<QueryPageResult> {
        self.expire_query_sessions();
        let Some(mut cursor) = self.query_sessions.remove(session_id) else {
            bail!("TDengine query session not found: {session_id}");
        };
        cursor.last_accessed_at = Instant::now();
        let page_size = normalized_page_size(page_size, 0, cursor.remaining_limit().max(1));
        let mut page = read_cursor_page(&mut cursor, page_size, token, timeout_secs).await?;
        let (has_more, truncated) = cursor.prepare_next_page(token, timeout_secs).await?;
        page.truncated = truncated;
        if has_more {
            page.session_id = Some(session_id.to_string());
            page.has_more = true;
            self.query_sessions.insert(session_id.to_string(), cursor);
        }
        Ok(page)
    }

    pub fn close_query_session(&mut self, session_id: &str) -> bool {
        self.query_sessions.remove(session_id).is_some()
    }

    fn expire_query_sessions(&mut self) {
        self.query_sessions.retain(|_, cursor| cursor.last_accessed_at.elapsed() <= QUERY_SESSION_IDLE_TIMEOUT);
    }

    pub async fn execute_statements(
        &mut self,
        statements: Vec<String>,
        database: &str,
        timeout_secs: u64,
        token: &CancellationToken,
    ) -> Result<QueryResult> {
        let start = Instant::now();
        if !database.trim().is_empty() {
            self.use_database(database, token, timeout_secs).await?;
        }
        let mut affected_rows = 0i64;
        for statement in &statements {
            let sql = trim_sql(statement);
            if sql.is_empty() {
                continue;
            }
            let result_set = cancellable(token, timeout_secs, self.require_connection()?.query(sql)).await?;
            affected_rows += i64::from(result_set.affected_rows());
        }
        if statements.iter().any(|statement| may_change_metadata(statement)) {
            invalidate_table_snapshots();
        }
        Ok(QueryResult {
            columns: Vec::new(),
            column_types: Vec::new(),
            rows: Vec::new(),
            affected_rows,
            execution_time_ms: start.elapsed().as_millis() as i64,
            truncated: false,
        })
    }

    pub async fn get_explain_info(&self, sql: &str, token: &CancellationToken, timeout_secs: u64) -> Result<String> {
        let sql = trim_sql(sql);
        if sql.is_empty() {
            bail!("SQL is required");
        }
        let rows = self.query_rows(&format!("EXPLAIN {sql}"), token, timeout_secs).await?;
        Ok(rows
            .into_iter()
            .map(|row| row.iter().map(display_json_value).collect::<Vec<_>>().join("\t"))
            .collect::<Vec<_>>()
            .join("\n"))
    }

    async fn prepare_database(&mut self, options: &QueryOptions, token: &CancellationToken) -> Result<()> {
        let database = if options.schema.trim().is_empty() { options.database.trim() } else { options.schema.trim() };
        if database.is_empty() || database == self.current_database {
            return Ok(());
        }
        self.use_database(database, token, options.timeout_secs).await
    }

    async fn use_database(&mut self, database: &str, token: &CancellationToken, timeout_secs: u64) -> Result<()> {
        let database = validate_database_name(database)?;
        let sql = format!("USE {database}");
        cancellable(token, timeout_secs, self.require_connection()?.exec(sql)).await?;
        self.current_database = database.to_string();
        Ok(())
    }

    async fn start_cursor(
        &self,
        sql: &str,
        max_rows: usize,
        token: &CancellationToken,
        timeout_secs: u64,
    ) -> Result<QueryCursor> {
        let sql = trim_sql(sql);
        if sql.is_empty() {
            bail!("SQL is required");
        }
        let result_set = cancellable(token, timeout_secs, self.require_connection()?.query(sql)).await?;
        let timezone = result_set.timezone();
        let columns = result_set.fields().iter().map(|field| field.name().to_string()).collect();
        let column_types = result_set.fields().iter().map(|field| field.ty().name().to_string()).collect();
        let affected_rows = i64::from(result_set.affected_rows());
        Ok(QueryCursor {
            result_set,
            timezone,
            session_timezone: self.session_timezone,
            columns,
            column_types,
            affected_rows,
            max_rows,
            rows_read: 0,
            pending_block: None,
            pending_row_index: 0,
            pending_row: None,
            last_accessed_at: Instant::now(),
        })
    }

    async fn query_rows(&self, sql: &str, token: &CancellationToken, timeout_secs: u64) -> Result<Vec<Vec<Value>>> {
        let mut cursor = self.start_cursor(sql, usize::MAX, token, timeout_secs).await?;
        let mut rows = Vec::new();
        while let Some(row) = cursor.next_row(token, timeout_secs).await? {
            rows.push(row);
        }
        Ok(rows)
    }

    async fn all_tables(&self, database: &str, token: &CancellationToken) -> Result<Arc<Vec<TableInfo>>> {
        let cache_key = self.table_cache_key(database);
        let generation = METADATA_GENERATION.load(Ordering::Relaxed);
        if let Some(tables) = cached_table_snapshot(&cache_key, generation) {
            return Ok(tables);
        }
        let mut tables = self
            .query_tables(&format!("SHOW {}STABLES", quote_qualified_prefix(database)), "STABLE", false, token)
            .await?;
        if uses_information_schema_tables(self.server_version.as_deref()) {
            tables.extend(self.query_information_schema_tables(database, token).await?);
        } else {
            // 2.x 的 SHOW TABLES 第 4 列就是所属超级表名,不需要额外的元数据扫描。
            tables.extend(
                self.query_tables(&format!("SHOW {}TABLES", quote_qualified_prefix(database)), "TABLE", true, token)
                    .await?,
            );
        }
        let mut seen = HashSet::new();
        tables.retain(|table| seen.insert(format!("{}:{}", table.table_type, table.name)));
        sort_tables_for_hierarchy(&mut tables);
        let tables = Arc::new(tables);
        store_table_snapshot(&cache_key, generation, tables.clone());
        Ok(tables)
    }

    /// 快照缓存键:连接指纹 + 数据库名。
    ///
    /// 一个 agent 进程可能承载多个连接,必须带上连接信息;密码不参与,避免把凭据
    /// 长期留在进程全局状态里。
    fn table_cache_key(&self, database: &str) -> String {
        format!(
            "{}|{}|{}|{}|{}|{}|{}",
            self.params.host,
            self.params.port,
            self.params.username,
            database,
            self.params.connection_string,
            self.params.url_params,
            self.params.ssl
        )
    }

    /// 读取数据库下的普通表和子表,并带上所属超级表名。
    ///
    /// `information_schema.ins_tables` 一次扫描就能同时得到表名和 `stable_name`,
    /// 避免先 `SHOW TABLES` 再全量扫描一遍 `ins_tables` 补齐父表(大库上的主要耗时点)。
    /// 该查询失败时重试一次而不是退回 `SHOW TABLES`:3.x 的 `SHOW TABLES` 没有
    /// `stable_name`,退回会让排序键从「按超级表分组」变成「按表名」,翻页时正是
    /// 会出现重复或漏表。仍失败则把错误抛给调用方,让侧栏显示错误而不是残缺列表。
    async fn query_information_schema_tables(
        &self,
        database: &str,
        token: &CancellationToken,
    ) -> Result<Vec<TableInfo>> {
        let sql = format!(
            "SELECT table_name, stable_name FROM information_schema.ins_tables WHERE db_name = {}",
            quote_literal(database)
        );
        let mut last_error = None;
        for _ in 0..2 {
            match self.query_rows(&sql, token, 0).await {
                Ok(rows) => return Ok(tables_from_information_schema_rows(rows)),
                Err(error) if token.is_cancelled() => return Err(error),
                Err(error) => last_error = Some(error),
            }
        }
        Err(last_error.unwrap_or_else(|| anyhow!("TDengine table metadata query failed")))
    }

    async fn query_tables(
        &self,
        sql: &str,
        table_type: &str,
        includes_stable_name: bool,
        token: &CancellationToken,
    ) -> Result<Vec<TableInfo>> {
        let rows = self.query_rows(sql, token, 0).await?;
        Ok(rows.into_iter().filter_map(|row| table_from_show_row(row, table_type, includes_stable_name)).collect())
    }

    async fn get_create_sql(
        &self,
        database: &str,
        name: &str,
        object_type: &str,
        token: &CancellationToken,
    ) -> Result<String> {
        let show_type = match object_type.trim().to_ascii_uppercase().as_str() {
            "STABLE" | "SUPER TABLE" | "SUPERTABLE" => "STABLE",
            "TABLE" | "BASE TABLE" | "CHILD TABLE" => "TABLE",
            _ => return Ok(String::new()),
        };
        let database = effective_database(database, &self.current_database)?;
        let rows = match self
            .query_rows(&format!("SHOW CREATE {show_type} {}", qualified_name(database, name)), token, 0)
            .await
        {
            Ok(rows) => rows,
            Err(error) if token.is_cancelled() => return Err(error),
            Err(_) => return Ok(String::new()),
        };
        let Some(row) = rows.first() else {
            return Ok(String::new());
        };
        for value in row.iter().skip(1) {
            if let Some(value) = json_text(value) {
                if value.to_ascii_uppercase().contains("CREATE") {
                    return Ok(value.to_string());
                }
            }
        }
        Ok(row.last().and_then(json_text).unwrap_or_default().to_string())
    }

    fn require_connection(&self) -> Result<&Taos> {
        self.connection.as_ref().ok_or_else(|| anyhow!("not connected"))
    }
}

impl QueryCursor {
    async fn next_row(&mut self, token: &CancellationToken, timeout_secs: u64) -> Result<Option<Vec<Value>>> {
        if self.rows_read >= self.max_rows {
            return Ok(None);
        }
        if let Some(row) = self.pending_row.take() {
            self.rows_read += 1;
            return Ok(Some(row));
        }
        let row = self.next_raw_row(token, timeout_secs).await?;
        if row.is_some() {
            self.rows_read += 1;
        }
        Ok(row)
    }

    async fn prepare_next_page(&mut self, token: &CancellationToken, timeout_secs: u64) -> Result<(bool, bool)> {
        if self.rows_read >= self.max_rows {
            return Ok((false, self.next_raw_row(token, timeout_secs).await?.is_some()));
        }
        if self.pending_row.is_some() {
            return Ok((true, false));
        }
        self.pending_row = self.next_raw_row(token, timeout_secs).await?;
        Ok((self.pending_row.is_some(), false))
    }

    fn remaining_limit(&self) -> usize {
        self.max_rows.saturating_sub(self.rows_read)
    }

    async fn next_raw_row(&mut self, token: &CancellationToken, timeout_secs: u64) -> Result<Option<Vec<Value>>> {
        loop {
            if let Some(block) = &self.pending_block {
                if self.pending_row_index < block.nrows() {
                    let timezone = preferred_timezone(self.timezone, block.timezone(), self.session_timezone);
                    let row_index = self.pending_row_index;
                    self.pending_row_index += 1;
                    let row = (0..block.ncols())
                        .map(|column| {
                            block
                                .get_ref(row_index, column)
                                .map(|value| borrowed_value_to_json(value, timezone))
                                .unwrap_or(Value::Null)
                        })
                        .collect();
                    return Ok(Some(row));
                }
            }
            self.pending_block = None;
            self.pending_row_index = 0;
            let block =
                cancellable(token, timeout_secs, poll_fn(|context| self.result_set.fetch_raw_block(context))).await?;
            match block {
                Some(block) if block.nrows() > 0 => self.pending_block = Some(block),
                Some(_) => continue,
                None => return Ok(None),
            }
        }
    }
}

async fn read_cursor_page(
    cursor: &mut QueryCursor,
    page_size: usize,
    token: &CancellationToken,
    timeout_secs: u64,
) -> Result<QueryPageResult> {
    let mut rows = Vec::with_capacity(page_size);
    while rows.len() < page_size {
        let Some(row) = cursor.next_row(token, timeout_secs).await? else {
            break;
        };
        rows.push(row);
    }
    Ok(QueryPageResult {
        columns: cursor.columns.clone(),
        column_types: cursor.column_types.clone(),
        rows,
        affected_rows: cursor.affected_rows,
        execution_time_ms: 0,
        truncated: false,
        session_id: None,
        has_more: false,
    })
}

async fn query_scalar_string(
    connection: &Taos,
    sql: &str,
    token: &CancellationToken,
    timeout_secs: u64,
) -> Result<String> {
    let mut result = cancellable(token, timeout_secs, connection.query(sql)).await?;
    let timezone = result.timezone();
    loop {
        let block = cancellable(token, timeout_secs, poll_fn(|context| result.fetch_raw_block(context))).await?;
        let Some(block) = block else {
            bail!("TDengine query returned no rows");
        };
        if block.nrows() == 0 || block.ncols() == 0 {
            continue;
        }
        let value = block.get_ref(0, 0).ok_or_else(|| anyhow!("TDengine query returned an empty value"))?;
        return match borrowed_value_to_json(value, preferred_timezone(timezone, block.timezone(), None)) {
            Value::String(value) => Ok(value),
            value => Ok(value.to_string()),
        };
    }
}

fn preferred_timezone(
    query_timezone: Option<Tz>,
    block_timezone: Option<Tz>,
    session_timezone: Option<Tz>,
) -> Option<Tz> {
    query_timezone.or(block_timezone).or(session_timezone)
}

fn parse_server_timezone(value: &str) -> Option<Tz> {
    value.split_whitespace().next()?.parse().ok()
}

async fn cancellable<T, F>(token: &CancellationToken, timeout_secs: u64, future: F) -> Result<T>
where
    F: Future<Output = taos::RawResult<T>>,
{
    tokio::pin!(future);
    let operation = async {
        if timeout_secs == 0 {
            future.await.map_err(anyhow::Error::from)
        } else {
            timeout(Duration::from_secs(timeout_secs), future)
                .await
                .map_err(|_| anyhow!("TDengine operation timed out after {timeout_secs} seconds"))?
                .map_err(anyhow::Error::from)
        }
    };
    tokio::select! {
        _ = token.cancelled() => bail!("TDengine operation was cancelled"),
        result = operation => result,
    }
}

fn effective_database<'a>(requested: &'a str, current: &'a str) -> Result<&'a str> {
    let requested = requested.trim();
    if !requested.is_empty() {
        return validate_database_name(requested);
    }
    let current = current.trim();
    if current.is_empty() {
        bail!("TDengine database is required");
    }
    validate_database_name(current)
}

fn validate_database_name(value: &str) -> Result<&str> {
    let value = value.trim();
    let mut chars = value.chars();
    let valid_start = chars.next().is_some_and(|char| char == '_' || char.is_ascii_alphabetic());
    if !valid_start || !chars.all(|char| char == '_' || char.is_ascii_alphanumeric()) {
        bail!("invalid TDengine database name: {value}");
    }
    Ok(value)
}

fn table_from_show_row(row: Vec<Value>, table_type: &str, includes_stable_name: bool) -> Option<TableInfo> {
    let name = row.first().and_then(json_text)?.to_string();
    let parent_name = includes_stable_name
        .then(|| row.get(3).and_then(json_text).map(str::trim).filter(|value| !value.is_empty()).map(str::to_string))
        .flatten();
    Some(TableInfo { name, table_type: table_type.to_string(), comment: None, parent_schema: None, parent_name })
}

/// 把 `information_schema.ins_tables` 的两列结果(`table_name`、`stable_name`)转成表信息。
///
/// `stable_name` 为空表示普通表,不属于任何超级表;空白值按空处理,避免把空格当成父表名。
/// 该结果同时承担「表列表」和「父表映射」两个职责,因此不再需要额外的 `ins_tables` 扫描。
fn tables_from_information_schema_rows(rows: Vec<Vec<Value>>) -> Vec<TableInfo> {
    rows.into_iter()
        .filter_map(|row| {
            let name = row.first().and_then(json_text)?;
            if name.is_empty() {
                return None;
            }
            let parent_name =
                row.get(1).and_then(json_text).map(str::trim).filter(|value| !value.is_empty()).map(str::to_string);
            Some(TableInfo {
                name: name.to_string(),
                table_type: "TABLE".to_string(),
                comment: None,
                parent_schema: None,
                parent_name,
            })
        })
        .collect()
}

fn parse_describe_columns(rows: Vec<Vec<Value>>) -> Vec<ColumnInfo> {
    rows.into_iter()
        .enumerate()
        .filter_map(|(index, row)| {
            let name = row.first().and_then(json_text)?.to_string();
            let data_type = row.get(1).and_then(json_text).unwrap_or_default().to_string();
            let note = row.get(3).and_then(json_text).map(str::to_string);
            let is_tag = note.as_deref().is_some_and(|note| note.to_ascii_uppercase().contains("TAG"));
            let is_primary_key = !is_tag
                && (index == 0
                    || note.as_deref().is_some_and(|note| note.to_ascii_uppercase().contains("COMPOSITE KEY")));
            Some(ColumnInfo {
                name,
                data_type: data_type.clone(),
                is_nullable: !is_primary_key,
                column_default: None,
                is_primary_key,
                extra: note,
                comment: is_tag.then(|| "TAG".to_string()),
                numeric_precision: type_numbers(&data_type, "decimal").map(|(precision, _)| precision),
                numeric_scale: type_numbers(&data_type, "decimal").and_then(|(_, scale)| scale),
                character_maximum_length: character_length(&data_type),
            })
        })
        .collect()
}

fn type_numbers(data_type: &str, expected: &str) -> Option<(u32, Option<u32>)> {
    let lower = data_type.trim().to_ascii_lowercase();
    if !(lower.starts_with(expected) || (expected == "decimal" && lower.starts_with("numeric"))) {
        return None;
    }
    let values = lower.strip_prefix(expected).or_else(|| lower.strip_prefix("numeric"))?.trim();
    let inner = values.strip_prefix('(')?.strip_suffix(')')?;
    let mut values = inner.split(',').map(str::trim);
    let precision = values.next()?.parse().ok()?;
    let scale = values.next().and_then(|value| value.parse().ok());
    Some((precision, scale))
}

fn character_length(data_type: &str) -> Option<u32> {
    let lower = data_type.trim().to_ascii_lowercase();
    ["binary", "nchar", "varchar", "varbinary", "geometry", "blob", "mediumblob"]
        .iter()
        .find_map(|prefix| type_numbers(&lower, prefix).map(|(length, _)| length))
}

fn filter_tables(tables: &[TableInfo], constraints: &MetadataListConstraints) -> Vec<TableInfo> {
    let filter = constraints.filter.trim().to_ascii_lowercase();
    let mut skipped = 0usize;
    let limit = if constraints.limit == 0 { usize::MAX } else { constraints.limit };
    tables
        .iter()
        .filter(|table| table_type_allowed(&constraints.object_types, &table.table_type))
        .filter(|table| {
            text_matches(&table.name, &filter)
                || table.comment.as_deref().is_some_and(|comment| text_matches(comment, &filter))
        })
        .filter(|_| {
            let include = skipped >= constraints.offset;
            skipped += 1;
            include
        })
        .take(limit)
        .cloned()
        .collect()
}

fn table_type_allowed(object_types: &[String], table_type: &str) -> bool {
    object_types.is_empty()
        || object_types
            .iter()
            .map(|value| normalize_object_type(value))
            .any(|value| value == normalize_object_type(table_type))
}

fn normalize_object_type(value: &str) -> String {
    let upper = value.trim().to_ascii_uppercase().replace(' ', "_");
    if upper == "STABLE" || upper == "BASE_TABLE" || upper.contains("TABLE") {
        "TABLE".into()
    } else if upper.contains("VIEW") {
        "VIEW".into()
    } else {
        upper
    }
}

fn text_matches(candidate: &str, filter: &str) -> bool {
    if filter.is_empty() {
        return true;
    }
    let candidate = candidate.to_ascii_lowercase();
    candidate.contains(filter) || (filter.chars().count() >= 2 && fuzzy_subsequence_matches(&candidate, filter))
}

fn fuzzy_subsequence_matches(candidate: &str, expected: &str) -> bool {
    let mut candidate = candidate.chars();
    expected.chars().all(|expected| candidate.by_ref().any(|value| value == expected))
}

fn completion_matches(candidate: &str, request: &CompletionAssistantRequest) -> bool {
    let mask = request.mask.trim();
    if mask.is_empty() {
        return true;
    }
    if request.case_sensitive {
        completion_match_mode(candidate, mask, &request.match_mode)
    } else {
        completion_match_mode(&candidate.to_ascii_lowercase(), &mask.to_ascii_lowercase(), &request.match_mode)
    }
}

fn completion_match_mode(candidate: &str, mask: &str, mode: &str) -> bool {
    match mode.trim().to_ascii_lowercase().as_str() {
        "prefix" => candidate.starts_with(mask),
        "exact" => candidate == mask,
        "subsequence" | "fuzzy" => fuzzy_subsequence_matches(candidate, mask),
        _ => candidate.contains(mask) || fuzzy_subsequence_matches(candidate, mask),
    }
}

/// 为元数据快照排序:保证所有根表(超级表 STABLE 和普通无父表 TABLE)排在前面,
/// 随后是属于各超级表的子表(按超级表分组,组内按子表名排序)。
///
/// 修复 #13728:TDengine 下若将子表直接交错在对应超级表后面,当某个超级表拥有
/// 大量子表(如 998 个甚至数万个)时,前端侧边栏按 1000 条分页请求首页,
/// 后续的超级表(第 3 个超级表及更多)会被排到 1000 条之后,导致侧边栏丢超级表。
/// 根表优先排序确保所有超级表与普通表优先出现在首页,子表再归属挂载。
fn sort_tables_for_hierarchy(tables: &mut [TableInfo]) {
    tables.sort_by(|left, right| {
        left.parent_name.is_some().cmp(&right.parent_name.is_some()).then_with(|| {
            if left.parent_name.is_none() {
                left.name.to_ascii_lowercase().cmp(&right.name.to_ascii_lowercase())
            } else {
                let left_group = left.parent_name.as_deref().unwrap_or(&left.name).to_ascii_lowercase();
                let right_group = right.parent_name.as_deref().unwrap_or(&right.name).to_ascii_lowercase();
                left_group
                    .cmp(&right_group)
                    .then_with(|| left.name.to_ascii_lowercase().cmp(&right.name.to_ascii_lowercase()))
            }
        })
    });
}

/// 3.x 起 `SHOW TABLES` 只返回 3 列(没有 `stable_name`),必须走 `information_schema`;
/// 2.x 继续用 `SHOW TABLES`,避免多跑一次注定失败的查询。版本号探测失败时按 3.x 处理。
fn uses_information_schema_tables(server_version: Option<&str>) -> bool {
    let major =
        server_version.and_then(|version| version.split('.').next()).and_then(|major| major.parse::<u32>().ok());
    matches!(major, None | Some(3..))
}

/// 读取未过期的表快照;只克隆 `Arc`,不复制列表本身。
fn cached_table_snapshot(cache_key: &str, generation: u64) -> Option<Arc<Vec<TableInfo>>> {
    let snapshots = TABLE_SNAPSHOTS.lock().expect("TDengine table snapshot cache lock poisoned");
    let snapshot = snapshots.get(cache_key)?;
    (snapshot.generation == generation && snapshot.loaded_at.elapsed() < TABLE_CACHE_TTL)
        .then(|| snapshot.tables.clone())
}

/// 写入表快照,并顺带清掉已过期的条目,避免进程长时间运行后无限增长。
fn store_table_snapshot(cache_key: &str, generation: u64, tables: Arc<Vec<TableInfo>>) {
    let mut snapshots = TABLE_SNAPSHOTS.lock().expect("TDengine table snapshot cache lock poisoned");
    snapshots.retain(|_, snapshot| snapshot.loaded_at.elapsed() < TABLE_CACHE_TTL);
    snapshots.insert(cache_key.to_string(), TableSnapshot { loaded_at: Instant::now(), generation, tables });
}

/// 元数据发生变化的 SQL 执行成功后调用:让本进程内所有会话的表快照立即失效。
fn invalidate_table_snapshots() {
    METADATA_GENERATION.fetch_add(1, Ordering::Relaxed);
}

fn build_fallback_table_ddl(database: &str, table: &str, columns: &[ColumnInfo]) -> String {
    let definitions = columns
        .iter()
        .filter(|column| column.comment.as_deref() != Some("TAG"))
        .map(|column| format!("  {} {}", quote_identifier(&column.name), column.data_type))
        .collect::<Vec<_>>()
        .join(",\n");
    format!("CREATE TABLE {} (\n{}\n);", qualified_name(database, table), definitions)
}

fn quote_identifier(value: &str) -> String {
    format!("`{}`", value.replace('`', "``"))
}

fn quote_literal(value: &str) -> String {
    format!("'{}'", value.replace('\'', "''"))
}

fn quote_qualified_prefix(database: &str) -> String {
    if database.trim().is_empty() {
        String::new()
    } else {
        format!("{}.", database.trim())
    }
}

fn qualified_name(database: &str, name: &str) -> String {
    if database.trim().is_empty() {
        quote_identifier(name)
    } else {
        format!("{}.{}", database.trim(), quote_identifier(name))
    }
}

fn json_text(value: &Value) -> Option<&str> {
    match value {
        Value::String(value) => Some(value),
        _ => None,
    }
}

fn display_json_value(value: &Value) -> String {
    match value {
        Value::Null => String::new(),
        Value::String(value) => value.clone(),
        value => value.to_string(),
    }
}

fn non_empty(value: &str) -> Option<String> {
    (!value.trim().is_empty()).then(|| value.trim().to_string())
}

fn is_system_database(value: &str) -> bool {
    value.eq_ignore_ascii_case("information_schema") || value.eq_ignore_ascii_case("performance_schema")
}

fn may_change_metadata(sql: &str) -> bool {
    let normalized = sql.trim().to_ascii_lowercase();
    ["create ", "drop ", "alter ", "rename ", "truncate "].iter().any(|prefix| normalized.starts_with(prefix))
}

fn trim_sql(sql: &str) -> &str {
    sql.trim().trim_end_matches(';').trim_end()
}

fn normalized_max_rows(max_rows: usize) -> usize {
    if max_rows == 0 {
        DEFAULT_MAX_ROWS
    } else {
        max_rows
    }
}

fn normalized_page_size(page_size: usize, fetch_size: usize, max_rows: usize) -> usize {
    let page_size = if page_size > 0 {
        page_size
    } else if fetch_size > 0 {
        fetch_size
    } else {
        500
    };
    page_size.min(max_rows.max(1))
}

fn connect_timeout(params: &ConnectParams) -> Duration {
    if params.connect_timeout_secs == 0 {
        DEFAULT_CONNECT_TIMEOUT
    } else {
        Duration::from_secs(params.connect_timeout_secs)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn filters_names_with_substrings_and_subsequences() {
        assert!(text_matches("sensor_metrics", "metrics"));
        assert!(text_matches("sensor_metrics", "snm"));
        assert!(!text_matches("sensor_metrics", "xyz"));
    }

    #[test]
    fn prefers_query_timezone_and_falls_back_to_block_timezone() {
        assert_eq!(
            preferred_timezone(Some(chrono_tz::UTC), Some(chrono_tz::Asia::Tokyo), Some(chrono_tz::Asia::Shanghai)),
            Some(chrono_tz::UTC)
        );
        assert_eq!(
            preferred_timezone(None, Some(chrono_tz::Asia::Tokyo), Some(chrono_tz::Asia::Shanghai)),
            Some(chrono_tz::Asia::Tokyo)
        );
        assert_eq!(preferred_timezone(None, None, Some(chrono_tz::Asia::Shanghai)), Some(chrono_tz::Asia::Shanghai));
        assert_eq!(preferred_timezone(None, None, None), None);
    }

    #[test]
    fn parses_tdengine_timezone_description() {
        assert_eq!(parse_server_timezone("Asia/Shanghai (CST, +0800)"), Some(chrono_tz::Asia::Shanghai));
        assert_eq!(parse_server_timezone("Etc/UTC (UTC, +0000)"), Some(chrono_tz::Etc::UTC));
        assert_eq!(parse_server_timezone("unknown (+0800)"), None);
    }

    #[test]
    fn sorts_stables_before_their_children() {
        let mut tables = vec![
            TableInfo {
                name: "d2".into(),
                table_type: "TABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: Some("meters".into()),
            },
            TableInfo {
                name: "meters".into(),
                table_type: "STABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: None,
            },
            TableInfo {
                name: "d1".into(),
                table_type: "TABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: Some("meters".into()),
            },
        ];
        sort_tables_for_hierarchy(&mut tables);
        assert_eq!(tables.iter().map(|table| table.name.as_str()).collect::<Vec<_>>(), vec!["meters", "d1", "d2"]);
    }

    #[test]
    fn sorts_supertables_before_child_tables_preventing_page_truncation() {
        // #13728: 3 个超级表,其中 stable_b 有 998 个子表;
        // 若按旧逻辑把子表排在 stable_b 之后,第 1000 个表后的 stable_c 会被截断到下一页。
        let mut tables = vec![
            TableInfo {
                name: "stable_a".into(),
                table_type: "STABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: None,
            },
            TableInfo {
                name: "stable_b".into(),
                table_type: "STABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: None,
            },
            TableInfo {
                name: "stable_c".into(),
                table_type: "STABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: None,
            },
        ];
        for i in 0..998 {
            tables.push(TableInfo {
                name: format!("sub_{:04}", i),
                table_type: "TABLE".into(),
                comment: None,
                parent_schema: None,
                parent_name: Some("stable_b".into()),
            });
        }
        sort_tables_for_hierarchy(&mut tables);
        // 所有超级表必须优先排在前面,不被前一个超级表的子表挤占分页
        assert_eq!(tables[0].name, "stable_a");
        assert_eq!(tables[1].name, "stable_b");
        assert_eq!(tables[2].name, "stable_c");
        assert_eq!(tables[3].name, "sub_0000");
        assert_eq!(tables[1000].name, "sub_0997");

        let first_page = filter_tables(
            &tables,
            &MetadataListConstraints { limit: 1000, offset: 0, ..MetadataListConstraints::default() },
        );
        let first_page_names: Vec<&str> = first_page.iter().map(|t| t.name.as_str()).collect();
        assert!(first_page_names.contains(&"stable_a"));
        assert!(first_page_names.contains(&"stable_b"));
        assert!(first_page_names.contains(&"stable_c"));
    }

    #[test]
    fn parses_tdengine_describe_metadata() {
        let columns = parse_describe_columns(vec![
            vec![json!("ts"), json!("TIMESTAMP"), json!(8), json!("")],
            vec![json!("device"), json!("VARCHAR(64)"), json!(64), json!("COMPOSITE KEY")],
            vec![json!("location"), json!("NCHAR(32)"), json!(32), json!("TAG")],
            vec![json!("reading"), json!("DECIMAL(20, 4)"), json!(16), Value::Null],
        ]);
        assert!(columns[0].is_primary_key);
        assert!(columns[1].is_primary_key);
        assert_eq!(columns[2].comment.as_deref(), Some("TAG"));
        assert_eq!(columns[2].character_maximum_length, Some(32));
        assert_eq!(columns[3].numeric_precision, Some(20));
        assert_eq!(columns[3].numeric_scale, Some(4));
    }

    #[test]
    fn converts_legacy_show_rows_to_hierarchy() {
        let table =
            table_from_show_row(vec![json!("d1001"), json!("x"), json!("x"), json!("meters")], "TABLE", true).unwrap();
        assert_eq!(table.parent_name.as_deref(), Some("meters"));
    }

    #[test]
    fn maps_information_schema_rows_to_child_tables() {
        let tables = tables_from_information_schema_rows(vec![
            vec![json!("d1"), json!("meters")],
            vec![json!("plain"), json!("")],
            vec![json!("padded"), json!("   ")],
            vec![json!("d2"), Value::Null],
            vec![Value::Null, json!("meters")],
        ]);
        assert_eq!(tables.len(), 4);
        assert!(tables.iter().all(|table| table.table_type == "TABLE"));
        assert_eq!(tables[0].parent_name.as_deref(), Some("meters"));
        assert_eq!(tables[1].parent_name, None);
        assert_eq!(tables[2].parent_name, None);
        assert_eq!(tables[3].parent_name, None);
    }

    #[test]
    fn pages_over_sorted_snapshot_without_gaps_or_overlaps() {
        let table = |name: &str, parent: Option<&str>| TableInfo {
            name: name.into(),
            table_type: "TABLE".into(),
            comment: None,
            parent_schema: None,
            parent_name: parent.map(str::to_string),
        };
        let mut snapshot = vec![
            table("meters", None),
            table("d2", Some("meters")),
            table("d1", Some("meters")),
            table("logs", None),
            table("d3", Some("meters")),
        ];
        sort_tables_for_hierarchy(&mut snapshot);

        let mut paged = Vec::new();
        let page_size = 2;
        for offset in (0..snapshot.len()).step_by(page_size) {
            let page = filter_tables(
                &snapshot,
                &MetadataListConstraints { limit: page_size, offset, ..MetadataListConstraints::default() },
            );
            paged.extend(page.into_iter().map(|table| table.name));
        }
        assert_eq!(paged, snapshot.iter().map(|table| table.name.clone()).collect::<Vec<_>>());
    }

    #[test]
    fn routes_table_metadata_by_server_version() {
        // 3.x 与探测失败都走 information_schema(SHOW TABLES 缺 stable_name)。
        assert!(uses_information_schema_tables(Some("3.2.3.0")));
        assert!(uses_information_schema_tables(Some("3.0.0.0")));
        assert!(uses_information_schema_tables(None));
        // 2.x 继续用 SHOW TABLES,避免多一次注定失败的查询。
        assert!(!uses_information_schema_tables(Some("2.6.0.0")));
    }

    #[test]
    fn drops_snapshots_when_metadata_generation_changes() {
        let key = "test|generation|tdengine";
        store_table_snapshot(key, 7, Arc::new(vec![]));
        assert!(cached_table_snapshot(key, 7).is_some());
        assert!(cached_table_snapshot(key, 8).is_none());
    }

    #[test]
    fn validates_database_names_before_using_unquoted_show_syntax() {
        assert_eq!(validate_database_name("Power_1").unwrap(), "Power_1");
        assert!(validate_database_name("power-data").is_err());
        assert!(validate_database_name("power; DROP DATABASE other").is_err());
        assert_eq!(quote_qualified_prefix("Power_1"), "Power_1.");
        assert_eq!(qualified_name("Power_1", "meters"), "Power_1.`meters`");
    }

    #[tokio::test]
    async fn cancellable_stops_pending_connector_operations() {
        let token = CancellationToken::new();
        token.cancel();
        let error = cancellable(&token, 0, std::future::pending::<taos::RawResult<()>>()).await.unwrap_err();
        assert!(error.to_string().contains("cancelled"));
    }
}