feat(visual-explain): add visual explain modal and analysis

Closes #22

Author: debba

README.md

@@ -456,12 +456,12 @@ pnpm tauri build
 ## Roadmap
 
 - [x] [[Feat]: Allow loading of multiple Databases per connection](https://github.com/debba/tabularis/issues/47)
+- [x] [Visual Explain Analyze](https://github.com/debba/tabularis/issues/22)
 - [x] [Plugin System](https://github.com/debba/tabularis/issues/19)
 - [ ] [Feature: Remote Control](https://github.com/debba/tabularis/issues/46)
 - [ ] [Command Palette](https://github.com/debba/tabularis/issues/25)
 - [ ] [JSON/JSONB Editor & Viewer](https://github.com/debba/tabularis/issues/24)
 - [ ] [SQL Formatting / Prettier](https://github.com/debba/tabularis/issues/23)
-- [ ] [Visual Explain Analyze](https://github.com/debba/tabularis/issues/22)
 - [ ] [Data Compare / Diff Tool](https://github.com/debba/tabularis/issues/21)
 - [ ] [Team Collaboration](https://github.com/debba/tabularis/issues/20)
 - [ ] [Query History](https://github.com/debba/tabularis/issues/18)

roadmap.json

@@ -4,6 +4,11 @@
     "done": true,
     "url": "https://github.com/debba/tabularis/issues/47"
   },
+  {
+    "label": "Visual Explain Analyze",
+    "done": true,
+    "url": "https://github.com/debba/tabularis/issues/22"
+  },
   {
     "label": "Plugin System",
     "done": true,
@@ -29,11 +34,6 @@
     "done": false,
     "url": "https://github.com/debba/tabularis/issues/23"
   },
-  {
-    "label": "Visual Explain Analyze",
-    "done": false,
-    "url": "https://github.com/debba/tabularis/issues/22"
-  },
   {
     "label": "Data Compare / Diff Tool",
     "done": false,

src-tauri/src/ai.rs

@@ -354,6 +354,14 @@ pub async fn explain_ai_query(app: AppHandle, req: AiExplainRequest) -> Result<S
     explain_query(app, req).await
 }
 
+#[tauri::command]
+pub async fn analyze_ai_explain_plan(
+    app: AppHandle,
+    req: AiExplainRequest,
+) -> Result<String, String> {
+    analyze_explain_plan(app, req).await
+}
+
 #[tauri::command]
 pub async fn generate_cell_name(app: AppHandle, req: AiCellNameRequest) -> Result<String, String> {
     generate_cellname(app, req).await
@@ -475,6 +483,42 @@ pub async fn explain_query(app: AppHandle, mut req: AiExplainRequest) -> Result<
     result
 }
 
+pub async fn analyze_explain_plan(
+    app: AppHandle,
+    mut req: AiExplainRequest,
+) -> Result<String, String> {
+    log::info!(
+        "Analyzing explain plan using AI provider: {}",
+        req.provider
+    );
+
+    let app_config = config::load_config_internal(&app);
+    let ollama_port = app_config.ai_ollama_port.unwrap_or(11434);
+    req.model = resolve_model(&req.provider, &req.model, &app_config, ollama_port).await?;
+
+    let raw_prompt = config::get_explainplan_prompt(app);
+    let system_prompt = raw_prompt.replace("{{LANGUAGE}}", &req.language);
+
+    let gen_req = AiGenerateRequest {
+        provider: req.provider.clone(),
+        model: req.model.clone(),
+        prompt: req.query.clone(),
+        schema: String::new(),
+    };
+
+    let result = dispatch_provider(&app_config, &gen_req, &system_prompt, ollama_port).await;
+
+    match &result {
+        Ok(_) => log::info!(
+            "Explain plan analysis generated successfully using {}",
+            req.model
+        ),
+        Err(e) => log::error!("Explain plan analysis failed: {}", e),
+    }
+
+    result
+}
+
 async fn generate_with_simple_prompt(
     app: AppHandle,
     provider: String,

src-tauri/src/commands.rs

@@ -10,8 +10,8 @@ use uuid::Uuid;
 use crate::credential_cache;
 use crate::keychain_utils;
 use crate::models::{
-    ColumnDefinition, ConnectionGroup, ConnectionParams, ConnectionsFile, ForeignKey, Index,
-    QueryResult, RoutineInfo, RoutineParameter, SavedConnection, SshConnection,
+    ColumnDefinition, ConnectionGroup, ConnectionParams, ConnectionsFile, ExplainPlan, ForeignKey,
+    Index, QueryResult, RoutineInfo, RoutineParameter, SavedConnection, SshConnection,
     SshConnectionInput, SshTestParams, TableColumn, TableInfo, TestConnectionRequest,
 };
 use crate::persistence;
@@ -2061,6 +2061,79 @@ pub async fn execute_query<R: Runtime>(
     }
 }
 
+// --- Explain Query Plan ---
+
+#[tauri::command]
+pub async fn explain_query_plan<R: Runtime>(
+    app: AppHandle<R>,
+    state: State<'_, QueryCancellationState>,
+    connection_id: String,
+    query: String,
+    analyze: bool,
+    schema: Option<String>,
+) -> Result<ExplainPlan, String> {
+    log::info!(
+        "Explaining query on connection: {} | analyze: {} | Query: {}",
+        connection_id,
+        analyze,
+        query
+    );
+
+    let sanitized_query = query
+        .trim()
+        .trim_end_matches(';')
+        .replace('\u{2018}', "'")
+        .replace('\u{2019}', "'")
+        .replace('\u{201C}', "\"")
+        .replace('\u{201D}', "\"")
+        .to_string();
+
+    if !crate::drivers::common::is_explainable_query(&sanitized_query) {
+        return Err(
+            "EXPLAIN is only supported for DML statements (SELECT, INSERT, UPDATE, DELETE, REPLACE). DDL statements like CREATE, DROP, or ALTER cannot be explained."
+                .into(),
+        );
+    }
+
+    let saved_conn = find_connection_by_id(&app, &connection_id)?;
+    let expanded_params = expand_ssh_connection_params(&app, &saved_conn.params).await?;
+    let params = resolve_connection_params_with_id(&expanded_params, &connection_id)?;
+
+    let drv = driver_for(&saved_conn.params.driver).await?;
+    let task = tokio::spawn(async move {
+        drv.explain_query(&params, &sanitized_query, analyze, schema.as_deref())
+            .await
+    });
+
+    let abort_handle = task.abort_handle();
+    {
+        let mut handles = state.handles.lock().unwrap();
+        handles.insert(format!("explain_{}", connection_id), abort_handle);
+    }
+
+    let result = task.await;
+
+    {
+        let mut handles = state.handles.lock().unwrap();
+        handles.remove(&format!("explain_{}", connection_id));
+    }
+
+    match result {
+        Ok(Ok(plan)) => {
+            log::info!("Explain query completed successfully");
+            Ok(plan)
+        }
+        Ok(Err(e)) => {
+            log::error!("Explain query failed: {}", e);
+            Err(e)
+        }
+        Err(_) => {
+            log::warn!("Explain query was cancelled");
+            Err("Explain query cancelled".into())
+        }
+    }
+}
+
 // --- Count Query ---
 
 #[tauri::command]

src-tauri/src/config.rs

@@ -380,6 +380,8 @@ pub fn check_ai_key_status(provider: String) -> AiKeyStatus {
 const DEFAULT_SYSTEM_PROMPT: &str = "You are an expert SQL assistant. Your task is to generate a SQL query based on the user's request and the provided database schema.\nReturn ONLY the SQL query, without any markdown formatting, explanations, or code blocks.\n\nSchema:\n{{SCHEMA}}";
 const DEFAULT_EXPLAIN_PROMPT: &str =
     "You are a helpful SQL assistant. Explain SQL queries in {{LANGUAGE}}.";
+const DEFAULT_EXPLAINPLAN_PROMPT: &str =
+    "You are a database performance expert. Analyze the following SQL query and its EXPLAIN plan output. Identify performance bottlenecks, suggest index improvements, and explain the execution strategy. Respond in {{LANGUAGE}}.";
 const DEFAULT_CELLNAME_PROMPT: &str = "You are an assistant that generates concise, descriptive names for notebook cells.\nGiven a SQL query or Markdown content, return ONLY a short name (3-6 words max) that describes what the cell does or what it is about.\nDo not include quotes, punctuation, or explanations. Just the name.";
 const DEFAULT_TABRENAME_PROMPT: &str = "You are an assistant that generates concise, descriptive names for SQL query result tabs.\nGiven a SQL query, return ONLY a short name (3-6 words max) that describes what the query does.\nDo not include quotes, punctuation, or explanations. Just the name.";
 
@@ -438,6 +440,19 @@ pub fn reset_explain_prompt(app: AppHandle) -> Result<String, String> {
     reset_prompt(&app, "prompt_explain.txt", DEFAULT_EXPLAIN_PROMPT)
 }
 
+#[tauri::command]
+pub fn get_explainplan_prompt(app: AppHandle) -> String {
+    get_prompt(&app, "prompt_explainplan.txt", DEFAULT_EXPLAINPLAN_PROMPT)
+}
+#[tauri::command]
+pub fn save_explainplan_prompt(app: AppHandle, prompt: String) -> Result<(), String> {
+    save_prompt(&app, "prompt_explainplan.txt", &prompt)
+}
+#[tauri::command]
+pub fn reset_explainplan_prompt(app: AppHandle) -> Result<String, String> {
+    reset_prompt(&app, "prompt_explainplan.txt", DEFAULT_EXPLAINPLAN_PROMPT)
+}
+
 #[tauri::command]
 pub fn get_cellname_prompt(app: AppHandle) -> String {
     get_prompt(&app, "prompt_cellname.txt", DEFAULT_CELLNAME_PROMPT)

src-tauri/src/drivers/common.rs

@@ -115,6 +115,46 @@ pub fn is_select_query(query: &str) -> bool {
     query.trim_start().to_uppercase().starts_with("SELECT")
 }
 
+/// Strip leading SQL comments (`-- …` line comments and `/* … */` block
+/// comments) and whitespace so the first statement keyword is at position 0.
+pub fn strip_leading_sql_comments(query: &str) -> &str {
+    let mut s = query;
+    loop {
+        s = s.trim_start();
+        if s.starts_with("--") {
+            match s.find('\n') {
+                Some(pos) => s = &s[pos + 1..],
+                None => return "",
+            }
+        } else if s.starts_with("/*") {
+            match s.find("*/") {
+                Some(pos) => s = &s[pos + 2..],
+                None => return "",
+            }
+        } else {
+            break;
+        }
+    }
+    s
+}
+
+/// Check if a query type supports EXPLAIN.
+///
+/// MySQL/MariaDB support EXPLAIN for DML statements only:
+/// SELECT, INSERT, UPDATE, DELETE, REPLACE, and WITH (CTE).
+/// DDL statements (CREATE, DROP, ALTER, TRUNCATE, etc.) are not supported.
+/// Leading SQL comments are stripped before checking.
+pub fn is_explainable_query(query: &str) -> bool {
+    let upper = strip_leading_sql_comments(query).to_uppercase();
+    upper.starts_with("SELECT")
+        || upper.starts_with("INSERT")
+        || upper.starts_with("UPDATE")
+        || upper.starts_with("DELETE")
+        || upper.starts_with("REPLACE")
+        || upper.starts_with("WITH")
+        || upper.starts_with("TABLE")
+}
+
 /// Calculate offset for pagination
 pub fn calculate_offset(page: u32, page_size: u32) -> u32 {
     (page - 1) * page_size
@@ -213,6 +253,95 @@ mod tests {
         assert_eq!(decoded, svg);
     }
 
+    #[test]
+    fn test_strip_leading_sql_comments_line() {
+        assert_eq!(
+            strip_leading_sql_comments("-- comment\nSELECT 1"),
+            "SELECT 1"
+        );
+        assert_eq!(
+            strip_leading_sql_comments("-- line1\n-- line2\nSELECT 1"),
+            "SELECT 1"
+        );
+    }
+
+    #[test]
+    fn test_strip_leading_sql_comments_block() {
+        assert_eq!(
+            strip_leading_sql_comments("/* block */ SELECT 1"),
+            "SELECT 1"
+        );
+        assert_eq!(
+            strip_leading_sql_comments("/* a */ /* b */ SELECT 1"),
+            "SELECT 1"
+        );
+    }
+
+    #[test]
+    fn test_strip_leading_sql_comments_mixed() {
+        assert_eq!(
+            strip_leading_sql_comments("-- line\n/* block */\nSELECT 1"),
+            "SELECT 1"
+        );
+    }
+
+    #[test]
+    fn test_strip_leading_sql_comments_no_comments() {
+        assert_eq!(strip_leading_sql_comments("SELECT 1"), "SELECT 1");
+        assert_eq!(strip_leading_sql_comments("  SELECT 1"), "SELECT 1");
+    }
+
+    #[test]
+    fn test_strip_leading_sql_comments_unterminated() {
+        assert_eq!(strip_leading_sql_comments("-- only comment"), "");
+        assert_eq!(strip_leading_sql_comments("/* never closed"), "");
+    }
+
+    #[test]
+    fn test_is_explainable_query_dml() {
+        assert!(is_explainable_query("SELECT * FROM users"));
+        assert!(is_explainable_query("  select * from users"));
+        assert!(is_explainable_query("INSERT INTO users VALUES (1)"));
+        assert!(is_explainable_query("UPDATE users SET name = 'test'"));
+        assert!(is_explainable_query("DELETE FROM users WHERE id = 1"));
+        assert!(is_explainable_query("REPLACE INTO users VALUES (1, 'a')"));
+        assert!(is_explainable_query("WITH cte AS (SELECT 1) SELECT * FROM cte"));
+        assert!(is_explainable_query("TABLE users"));
+    }
+
+    #[test]
+    fn test_is_explainable_query_ddl() {
+        assert!(!is_explainable_query("CREATE INDEX idx ON t(col)"));
+        assert!(!is_explainable_query("CREATE TABLE users (id INT)"));
+        assert!(!is_explainable_query("DROP TABLE users"));
+        assert!(!is_explainable_query("ALTER TABLE users ADD COLUMN name TEXT"));
+        assert!(!is_explainable_query("TRUNCATE TABLE users"));
+        assert!(!is_explainable_query("GRANT SELECT ON users TO 'user'"));
+        assert!(!is_explainable_query("REVOKE SELECT ON users FROM 'user'"));
+    }
+
+    #[test]
+    fn test_is_explainable_query_whitespace() {
+        assert!(is_explainable_query("\n\t  SELECT 1"));
+        assert!(!is_explainable_query("\n\t  CREATE INDEX idx ON t(col)"));
+    }
+
+    #[test]
+    fn test_is_explainable_query_with_comments() {
+        assert!(is_explainable_query(
+            "-- BEFORE index: full scan\nSELECT * FROM audit_log"
+        ));
+        assert!(is_explainable_query(
+            "/* explain this */ SELECT * FROM users"
+        ));
+        assert!(is_explainable_query(
+            "-- comment\n-- another\nDELETE FROM users WHERE id = 1"
+        ));
+        assert!(!is_explainable_query(
+            "-- setup\nCREATE INDEX idx ON t(col)"
+        ));
+    }
+
     #[test]
     fn test_is_select_query() {
         assert!(is_select_query("SELECT * FROM users"));

src-tauri/src/drivers/driver_trait.rs

@@ -7,8 +7,8 @@ use sqlx::{AnyConnection, Connection};
 use std::str::FromStr;
 
 use crate::models::{
-    ColumnDefinition, ConnectionParams, DataTypeInfo, ForeignKey, Index, QueryResult, RoutineInfo,
-    RoutineParameter, TableColumn, TableInfo, TableSchema, ViewInfo,
+    ColumnDefinition, ConnectionParams, DataTypeInfo, ExplainPlan, ForeignKey, Index, QueryResult,
+    RoutineInfo, RoutineParameter, TableColumn, TableInfo, TableSchema, ViewInfo,
 };
 
 /// Capabilities advertised by a driver.
@@ -309,6 +309,19 @@ pub trait DatabaseDriver: Send + Sync {
         schema: Option<&str>,
     ) -> Result<QueryResult, String>;
 
+    /// Runs EXPLAIN (or EXPLAIN ANALYZE) on the given query and returns a
+    /// parsed execution plan tree. Drivers that do not support EXPLAIN can
+    /// rely on the default implementation which returns an error.
+    async fn explain_query(
+        &self,
+        _params: &ConnectionParams,
+        _query: &str,
+        _analyze: bool,
+        _schema: Option<&str>,
+    ) -> Result<ExplainPlan, String> {
+        Err("EXPLAIN not supported by this driver".into())
+    }
+
     // --- CRUD ---------------------------------------------------------------
 
     async fn insert_record(