openduck-cli 0.1.0__tar.gz

openduck_cli-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: openduck-cli
+Version: 0.1.0
+Summary: The Modern, Lightning-Fast Terminal SQL IDE & Data Explorer for DuckDB
+Author: Bertatron
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: textual[syntax]>=0.50.0
+Requires-Dist: duckdb>=0.9.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pyinstaller; extra == "dev"
+Provides-Extra: db
+Requires-Dist: pymssql; extra == "db"
+
+# 🦆 OpenDuck
+
+<p align="center">
+  <b>The Modern, Lightning-Fast Terminal SQL IDE & Data Explorer for DuckDB</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
+  <img src="https://img.shields.io/badge/DuckDB-Fast%20Analytics-yellow?style=for-the-badge&logo=duckdb&logoColor=black" alt="DuckDB" />
+  <img src="https://img.shields.io/badge/TUI-Textual-green?style=for-the-badge" alt="Textual" />
+  <img src="https://img.shields.io/badge/License-MIT-orange?style=for-the-badge" alt="MIT License" />
+</p>
+
+---
+
+<p align="center">
+  <img width="100%" alt="OpenDuck Interface" src="https://github.com/user-attachments/assets/4aea9df6-6f00-494d-a171-d76a9a3b8133" />
+</p>
+
+**OpenDuck** brings the power and speed of **DuckDB** straight to your terminal in an intuitive, multi-tab Text User Interface (TUI). Effortlessly browse files, inspect datasets, write queries with full syntax highlighting, sort and filter millions of rows in milliseconds, and export results — all without leaving your shell.
+
+---
+
+## ✨ Features
+
+- ⚡ **Instant File Queries**: Click or select any file (`.csv`, `.parquet`, `.xlsx`, `.json`, `.duckdb`, `.sqlite`, `.arrow`) from the sidebar to instantly load and execute queries with zero boilerplates.
+- 🎨 **Rich SQL Syntax Highlighting**: Tree-sitter powered VS Code Dark styling with real-time token highlighting for SQL keywords, strings, numbers, identifiers, and comments.
+- 🚀 **Asynchronous & Non-Blocking**: Queries execute in dedicated background threads — the interface remains buttery smooth and never freezes, even on heavy multi-gigabyte queries.
+- 📑 **Multi-Tab Workspace**: Work with multiple datasets simultaneously with tab navigation, close buttons (`✕`), and tab titles dynamically bound to files and queries.
+- 📊 **Interactive Data Viewer**:
+  - Sort columns ascending/descending with clickable headers (safe null handling).
+  - Quick column filters.
+  - Live query execution runtime, row count, and memory consumption stats.
+- 📋 **Terminal & System Clipboard Integration**:
+  - Copy highlighted cells or entire rows (`Ctrl+C`).
+  - Copy full query results as TSV (`Ctrl+A`).
+  - Native terminal copy & paste with multi-level Undo/Redo (`Cmd+Z` / `Ctrl+Z` / `Ctrl+Y`).
+  - Toggle SQL comments effortlessly (`F3` / `Cmd+/`).
+- 💾 **One-Click Export**: Export results to `.csv` or `.xlsx` files with a single click.
+- 📜 **History & Saved Queries**: Automatically preserves query history and lets you save reusable named queries with quick one-click recall into your editor.
+- 🎛️ **Draggable Resizable Sidebar**: Adjust the width of your sidebar on the fly with mouse drag.
+- 🛡️ **Intelligent Error Diagnostics**: Corrupted file, wrong delimiter, permission issue, or missing dataset? OpenDuck identifies the exact cause and displays human-readable actionable solutions.
+- 🐇 **Easter Egg**: Secret Matrix rain screensaver!
+
+---
+
+## 📂 Supported File Formats
+
+OpenDuck automatically recognises and formats queries for:
+
+| Format | Extensions | Query Mode |
+| :--- | :--- | :--- |
+| **Parquet** | `.parquet` | Native direct query |
+| **Arrow** | `.arrow` | Native direct query |
+| **CSV & GZ** | `.csv`, `.csv.gz` | `read_csv_auto(...)` |
+| **JSON & JSONL** | `.json`, `.jsonl` | `read_json_auto(...)` |
+| **Excel** | `.xlsx`, `.xls` | In-memory table registration (`pandas` + `openpyxl`) |
+| **SQLite** | `.sqlite`, `.sqlite3`, `.db` | Automatic SQLite extension attach |
+| **DuckDB** | `.duckdb` | Database attach & table explore |
+
+---
+
+## 🚀 Quickstart
+
+### 1. Installation
+
+**Via PyPI:**
+```bash
+pip install openduck-cli
+```
+
+**From source:**
+```bash
+git clone https://github.com/klandermans/openduck.git
+cd openduck
+pip install -r requirements.txt
+# or: pip install -e .
+```
+
+> **Note:** `textual[syntax]` installs the required `tree-sitter` and `tree-sitter-sql` engines for syntax highlighting out of the box.
+
+### 2. Run OpenDuck
+
+```bash
+python openduck.py
+```
+
+Or make it available system-wide as a command:
+
+```bash
+chmod +x openduck.sh
+sudo cp openduck.sh /usr/local/bin/openduck
+openduck
+```
+
+---
+
+## ⌨️ Keyboard & Mouse Shortcuts
+
+| Shortcut | Description |
+| :--- | :--- |
+| `Ctrl+Enter` / `Cmd+Enter` | **Run Query** (runs selection if text is selected, or full editor) |
+| `Ctrl+S` / `Cmd+S` | **Save Query** with custom name to `openduck.json` |
+| `F3` / `Cmd+/` / `Ctrl+/` | **Toggle SQL Comment** (`--`) on current line or selection |
+| `Ctrl+Z` / `Cmd+Z` | **Undo** last edit |
+| `Ctrl+Y` / `Cmd+Shift+Z` | **Redo** undone edit |
+| `Ctrl+W` / `Cmd+W` | **Close Current Tab** |
+| `Ctrl+M` | **Toggle Mouse Mode** (switch between TUI mouse and native terminal text selection) |
+| `Ctrl+C` / `Cmd+C` | **Copy** (Editor selection, or table row/cell to system clipboard) |
+| `Ctrl+A` / `Cmd+A` | **Copy Table** (when focused on results) / Select all (in editor) |
+| `F1` | **About Dialog** (click the duck for a surprise! 🕶️) |
+| `Ctrl+Q` / `Cmd+Q` | **Quit** OpenDuck |
+
+---
+
+## ⚙️ Configuration & Storage
+
+OpenDuck automatically manages `openduck.json` in your working directory. It persists:
+- The last 200 executed queries in chronological order.
+- Your named saved queries.
+- Database configurations.
+
+```json
+{
+  "history": [
+    {
+      "sql": "SELECT * FROM read_csv_auto('sales.csv') WHERE revenue > 1000 LIMIT 100;",
+      "timestamp": "2026-10-14T15:30:00.123456"
+    }
+  ],
+  "saved_queries": [
+    {
+      "name": "Q3 Revenue by Region",
+      "sql": "SELECT region, SUM(amount) FROM read_parquet('data/*.parquet') GROUP BY region;",
+      "timestamp": "2026-10-14T15:32:00.654321"
+    }
+  ],
+  "connections": []
+}
+```
+
+---
+
+## 💡 Tips & Tricks
+
+- **Click to Query**: Clicking any file in the left sidebar automatically populates the query into your active tab, updates the tab name, and executes the preview.
+- **Run Selection Only**: Highlight any part of your SQL script and press `Ctrl+Enter` to run only the highlighted snippet — just like in DBeaver, DataGrip, or VS Code!
+- **Selective Comments**: Select multiple lines and press `F3` or `Cmd+/` to comment or uncomment SQL blocks simultaneously.
+- **Instant Clipboard Sharing**: Results copied via `Ctrl+C` or `Ctrl+A` are immediately synced to your macOS (`pbcopy`), Linux (`wl-copy`/`xclip`), or Windows clipboard.
+
+---
+
+## 📁 Project Structure
+
+```text
+openduck/
+├── openduck/                 # Core Python package
+│   ├── __init__.py           # Package entry and exports
+│   ├── __main__.py           # CLI invocation (python -m openduck)
+│   ├── main.py               # Application bootstrap & logging setup
+│   ├── core/                 # Core logic & backend
+│   │   ├── config.py         # Config persistence, query history, saved queries
+│   │   ├── clipboard.py      # Cross-platform system clipboard integration
+│   │   ├── sql_utils.py      # SQL formatting, file-to-query mapper, comments
+│   │   └── error_classifier.py # Diagnostic error classifier
+│   └── gui/                  # Textual user interface
+│       ├── app.py            # Main DuckCLI application
+│       ├── styles.py         # Textual CSS stylesheets
+│       ├── screens/          # Modal screens (About, Matrix screensaver)
+│       ├── dialogs/          # Modal dialogs (Save Query, Export, Add DB)
+│       └── widgets/          # Custom widgets (Editor, ResultsTable, Trees, etc.)
+├── docs/                     # Documentation & guides
+├── scripts/                  # Build scripts & packaging specs
+├── tests/                    # Automated test suite
+├── samples/                  # Sample datasets for testing & exploration
+├── openduck.py               # Root executable script
+├── openduck.sh               # Shell launcher script
+└── pyproject.toml            # Python package configuration
+```
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**. See `LICENSE` for details.
+

openduck_cli-0.1.0/README.md

@@ -0,0 +1,186 @@
+# 🦆 OpenDuck
+
+<p align="center">
+  <b>The Modern, Lightning-Fast Terminal SQL IDE & Data Explorer for DuckDB</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
+  <img src="https://img.shields.io/badge/DuckDB-Fast%20Analytics-yellow?style=for-the-badge&logo=duckdb&logoColor=black" alt="DuckDB" />
+  <img src="https://img.shields.io/badge/TUI-Textual-green?style=for-the-badge" alt="Textual" />
+  <img src="https://img.shields.io/badge/License-MIT-orange?style=for-the-badge" alt="MIT License" />
+</p>
+
+---
+
+<p align="center">
+  <img width="100%" alt="OpenDuck Interface" src="https://github.com/user-attachments/assets/4aea9df6-6f00-494d-a171-d76a9a3b8133" />
+</p>
+
+**OpenDuck** brings the power and speed of **DuckDB** straight to your terminal in an intuitive, multi-tab Text User Interface (TUI). Effortlessly browse files, inspect datasets, write queries with full syntax highlighting, sort and filter millions of rows in milliseconds, and export results — all without leaving your shell.
+
+---
+
+## ✨ Features
+
+- ⚡ **Instant File Queries**: Click or select any file (`.csv`, `.parquet`, `.xlsx`, `.json`, `.duckdb`, `.sqlite`, `.arrow`) from the sidebar to instantly load and execute queries with zero boilerplates.
+- 🎨 **Rich SQL Syntax Highlighting**: Tree-sitter powered VS Code Dark styling with real-time token highlighting for SQL keywords, strings, numbers, identifiers, and comments.
+- 🚀 **Asynchronous & Non-Blocking**: Queries execute in dedicated background threads — the interface remains buttery smooth and never freezes, even on heavy multi-gigabyte queries.
+- 📑 **Multi-Tab Workspace**: Work with multiple datasets simultaneously with tab navigation, close buttons (`✕`), and tab titles dynamically bound to files and queries.
+- 📊 **Interactive Data Viewer**:
+  - Sort columns ascending/descending with clickable headers (safe null handling).
+  - Quick column filters.
+  - Live query execution runtime, row count, and memory consumption stats.
+- 📋 **Terminal & System Clipboard Integration**:
+  - Copy highlighted cells or entire rows (`Ctrl+C`).
+  - Copy full query results as TSV (`Ctrl+A`).
+  - Native terminal copy & paste with multi-level Undo/Redo (`Cmd+Z` / `Ctrl+Z` / `Ctrl+Y`).
+  - Toggle SQL comments effortlessly (`F3` / `Cmd+/`).
+- 💾 **One-Click Export**: Export results to `.csv` or `.xlsx` files with a single click.
+- 📜 **History & Saved Queries**: Automatically preserves query history and lets you save reusable named queries with quick one-click recall into your editor.
+- 🎛️ **Draggable Resizable Sidebar**: Adjust the width of your sidebar on the fly with mouse drag.
+- 🛡️ **Intelligent Error Diagnostics**: Corrupted file, wrong delimiter, permission issue, or missing dataset? OpenDuck identifies the exact cause and displays human-readable actionable solutions.
+- 🐇 **Easter Egg**: Secret Matrix rain screensaver!
+
+---
+
+## 📂 Supported File Formats
+
+OpenDuck automatically recognises and formats queries for:
+
+| Format | Extensions | Query Mode |
+| :--- | :--- | :--- |
+| **Parquet** | `.parquet` | Native direct query |
+| **Arrow** | `.arrow` | Native direct query |
+| **CSV & GZ** | `.csv`, `.csv.gz` | `read_csv_auto(...)` |
+| **JSON & JSONL** | `.json`, `.jsonl` | `read_json_auto(...)` |
+| **Excel** | `.xlsx`, `.xls` | In-memory table registration (`pandas` + `openpyxl`) |
+| **SQLite** | `.sqlite`, `.sqlite3`, `.db` | Automatic SQLite extension attach |
+| **DuckDB** | `.duckdb` | Database attach & table explore |
+
+---
+
+## 🚀 Quickstart
+
+### 1. Installation
+
+**Via PyPI:**
+```bash
+pip install openduck-cli
+```
+
+**From source:**
+```bash
+git clone https://github.com/klandermans/openduck.git
+cd openduck
+pip install -r requirements.txt
+# or: pip install -e .
+```
+
+> **Note:** `textual[syntax]` installs the required `tree-sitter` and `tree-sitter-sql` engines for syntax highlighting out of the box.
+
+### 2. Run OpenDuck
+
+```bash
+python openduck.py
+```
+
+Or make it available system-wide as a command:
+
+```bash
+chmod +x openduck.sh
+sudo cp openduck.sh /usr/local/bin/openduck
+openduck
+```
+
+---
+
+## ⌨️ Keyboard & Mouse Shortcuts
+
+| Shortcut | Description |
+| :--- | :--- |
+| `Ctrl+Enter` / `Cmd+Enter` | **Run Query** (runs selection if text is selected, or full editor) |
+| `Ctrl+S` / `Cmd+S` | **Save Query** with custom name to `openduck.json` |
+| `F3` / `Cmd+/` / `Ctrl+/` | **Toggle SQL Comment** (`--`) on current line or selection |
+| `Ctrl+Z` / `Cmd+Z` | **Undo** last edit |
+| `Ctrl+Y` / `Cmd+Shift+Z` | **Redo** undone edit |
+| `Ctrl+W` / `Cmd+W` | **Close Current Tab** |
+| `Ctrl+M` | **Toggle Mouse Mode** (switch between TUI mouse and native terminal text selection) |
+| `Ctrl+C` / `Cmd+C` | **Copy** (Editor selection, or table row/cell to system clipboard) |
+| `Ctrl+A` / `Cmd+A` | **Copy Table** (when focused on results) / Select all (in editor) |
+| `F1` | **About Dialog** (click the duck for a surprise! 🕶️) |
+| `Ctrl+Q` / `Cmd+Q` | **Quit** OpenDuck |
+
+---
+
+## ⚙️ Configuration & Storage
+
+OpenDuck automatically manages `openduck.json` in your working directory. It persists:
+- The last 200 executed queries in chronological order.
+- Your named saved queries.
+- Database configurations.
+
+```json
+{
+  "history": [
+    {
+      "sql": "SELECT * FROM read_csv_auto('sales.csv') WHERE revenue > 1000 LIMIT 100;",
+      "timestamp": "2026-10-14T15:30:00.123456"
+    }
+  ],
+  "saved_queries": [
+    {
+      "name": "Q3 Revenue by Region",
+      "sql": "SELECT region, SUM(amount) FROM read_parquet('data/*.parquet') GROUP BY region;",
+      "timestamp": "2026-10-14T15:32:00.654321"
+    }
+  ],
+  "connections": []
+}
+```
+
+---
+
+## 💡 Tips & Tricks
+
+- **Click to Query**: Clicking any file in the left sidebar automatically populates the query into your active tab, updates the tab name, and executes the preview.
+- **Run Selection Only**: Highlight any part of your SQL script and press `Ctrl+Enter` to run only the highlighted snippet — just like in DBeaver, DataGrip, or VS Code!
+- **Selective Comments**: Select multiple lines and press `F3` or `Cmd+/` to comment or uncomment SQL blocks simultaneously.
+- **Instant Clipboard Sharing**: Results copied via `Ctrl+C` or `Ctrl+A` are immediately synced to your macOS (`pbcopy`), Linux (`wl-copy`/`xclip`), or Windows clipboard.
+
+---
+
+## 📁 Project Structure
+
+```text
+openduck/
+├── openduck/                 # Core Python package
+│   ├── __init__.py           # Package entry and exports
+│   ├── __main__.py           # CLI invocation (python -m openduck)
+│   ├── main.py               # Application bootstrap & logging setup
+│   ├── core/                 # Core logic & backend
+│   │   ├── config.py         # Config persistence, query history, saved queries
+│   │   ├── clipboard.py      # Cross-platform system clipboard integration
+│   │   ├── sql_utils.py      # SQL formatting, file-to-query mapper, comments
+│   │   └── error_classifier.py # Diagnostic error classifier
+│   └── gui/                  # Textual user interface
+│       ├── app.py            # Main DuckCLI application
+│       ├── styles.py         # Textual CSS stylesheets
+│       ├── screens/          # Modal screens (About, Matrix screensaver)
+│       ├── dialogs/          # Modal dialogs (Save Query, Export, Add DB)
+│       └── widgets/          # Custom widgets (Editor, ResultsTable, Trees, etc.)
+├── docs/                     # Documentation & guides
+├── scripts/                  # Build scripts & packaging specs
+├── tests/                    # Automated test suite
+├── samples/                  # Sample datasets for testing & exploration
+├── openduck.py               # Root executable script
+├── openduck.sh               # Shell launcher script
+└── pyproject.toml            # Python package configuration
+```
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**. See `LICENSE` for details.
+

openduck_cli-0.1.0/openduck/__init__.py

@@ -0,0 +1,42 @@
+"""OpenDuck - The Modern Terminal SQL IDE & Data Explorer for DuckDB."""
+
+__version__ = "0.1.0"
+
+from openduck.core.config import (
+    CWD,
+    CONFIG_FILE,
+    MAX_UI_ROWS,
+    DUCKDB_EXTENSIONS,
+    add_to_history,
+    delete_connection,
+    load_config,
+    save_config,
+    save_connection,
+    save_query,
+)
+from openduck.core.error_classifier import classify_file_error
+from openduck.core.sql_utils import is_duckdb_file, sql_for_file, toggle_sql_comment_lines
+from openduck.core.clipboard import copy_to_system_clipboard, get_system_clipboard
+from openduck.gui.app import DuckCLI
+from openduck.main import main
+
+__all__ = [
+    "DuckCLI",
+    "main",
+    "load_config",
+    "save_config",
+    "add_to_history",
+    "save_query",
+    "save_connection",
+    "delete_connection",
+    "classify_file_error",
+    "is_duckdb_file",
+    "sql_for_file",
+    "toggle_sql_comment_lines",
+    "copy_to_system_clipboard",
+    "get_system_clipboard",
+    "CWD",
+    "CONFIG_FILE",
+    "MAX_UI_ROWS",
+    "DUCKDB_EXTENSIONS",
+]

openduck_cli-0.1.0/openduck/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running openduck as a module: python -m openduck."""
+
+from openduck.main import main
+
+if __name__ == "__main__":
+    main()

openduck_cli-0.1.0/openduck/core/__init__.py

@@ -0,0 +1,36 @@
+"""Core modules for OpenDuck: config, clipboard, SQL utilities, and error classification."""
+
+from openduck.core.clipboard import copy_to_system_clipboard, get_system_clipboard
+from openduck.core.config import (
+    CONFIG_FILE,
+    CWD,
+    DUCKDB_EXTENSIONS,
+    MAX_UI_ROWS,
+    add_to_history,
+    delete_connection,
+    load_config,
+    save_config,
+    save_connection,
+    save_query,
+)
+from openduck.core.error_classifier import classify_file_error
+from openduck.core.sql_utils import is_duckdb_file, sql_for_file, toggle_sql_comment_lines
+
+__all__ = [
+    "CWD",
+    "CONFIG_FILE",
+    "MAX_UI_ROWS",
+    "DUCKDB_EXTENSIONS",
+    "load_config",
+    "save_config",
+    "add_to_history",
+    "save_query",
+    "save_connection",
+    "delete_connection",
+    "copy_to_system_clipboard",
+    "get_system_clipboard",
+    "is_duckdb_file",
+    "sql_for_file",
+    "toggle_sql_comment_lines",
+    "classify_file_error",
+]

openduck_cli-0.1.0/openduck/core/clipboard.py

@@ -0,0 +1,57 @@
+"""Cross-platform system clipboard integration."""
+
+import logging
+import subprocess
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def copy_to_system_clipboard(text: str) -> bool:
+    """Copy text to system clipboard (macOS pbcopy, xclip/wl-copy on Linux, clip on Windows)."""
+    if not text:
+        return False
+    try:
+        if sys.platform == "darwin":
+            p = subprocess.Popen(["pbcopy"], stdin=subprocess.PIPE, text=True)
+            p.communicate(input=text)
+            return True
+        elif sys.platform.startswith("linux"):
+            for cmd in (
+                ["wl-copy"],
+                ["xclip", "-selection", "clipboard"],
+                ["xsel", "--clipboard", "--input"],
+            ):
+                try:
+                    p = subprocess.Popen(cmd, stdin=subprocess.PIPE, text=True)
+                    p.communicate(input=text)
+                    return True
+                except FileNotFoundError:
+                    continue
+        elif sys.platform == "win32":
+            p = subprocess.Popen(["clip"], stdin=subprocess.PIPE, text=True)
+            p.communicate(input=text)
+            return True
+    except Exception as e:
+        logger.error(f"Failed to copy to system clipboard: {e}")
+    return False
+
+
+def get_system_clipboard() -> str:
+    """Read text from system clipboard (macOS pbpaste, wl-paste/xclip on Linux)."""
+    try:
+        if sys.platform == "darwin":
+            return subprocess.check_output(["pbpaste"], text=True)
+        elif sys.platform.startswith("linux"):
+            for cmd in (
+                ["wl-paste"],
+                ["xclip", "-selection", "clipboard", "-o"],
+                ["xsel", "--clipboard", "--output"],
+            ):
+                try:
+                    return subprocess.check_output(cmd, text=True)
+                except FileNotFoundError:
+                    continue
+    except Exception as e:
+        logger.error(f"Failed to read from system clipboard: {e}")
+    return ""

openduck_cli-0.1.0/openduck/core/config.py

@@ -0,0 +1,108 @@
+"""Configuration and persistence management for OpenDuck."""
+
+from datetime import datetime
+import json
+import logging
+import os
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CWD = Path(os.getcwd())
+CONFIG_FILE = CWD / "openduck.json"
+MAX_UI_ROWS = 10000
+DUCKDB_EXTENSIONS = {
+    ".parquet", ".arrow", ".duckdb", ".csv", ".csv.gz",
+    ".json", ".jsonl", ".sqlite", ".sqlite3", ".db", ".xlsx", ".xls"
+}
+
+
+def load_config() -> dict:
+    """Load config from openduck.json, create if doesn't exist or is invalid."""
+    if CONFIG_FILE.exists():
+        try:
+            with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                config = json.load(f)
+                if isinstance(config, dict):
+                    if "connections" not in config:
+                        config["connections"] = []
+                    if "history" not in config:
+                        config["history"] = []
+                    if "saved_queries" not in config:
+                        config["saved_queries"] = []
+                    return config
+        except Exception as e:
+            logger.error(f"Failed to read config file, falling back to default: {e}")
+
+    default_config = {
+        "history": [],
+        "saved_queries": [],
+        "connections": []
+    }
+    save_config(default_config)
+    return default_config
+
+
+def save_config(config: dict) -> None:
+    """Save config to openduck.json."""
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+
+
+def add_to_history(sql: str) -> dict:
+    """Add a query to history in the config file, capped at the last 200 queries."""
+    config = load_config()
+    timestamp = datetime.now().isoformat()
+    config["history"].append({
+        "sql": sql.strip(),
+        "timestamp": timestamp
+    })
+    # Keep only the last 200 queries to prevent boundless file growth
+    config["history"] = config["history"][-200:]
+    save_config(config)
+    return config
+
+
+def save_query(name: str, sql: str) -> dict:
+    """Save a query with a name to the config file."""
+    config = load_config()
+    timestamp = datetime.now().isoformat()
+    # Check if query with same name already exists and update it
+    for i, query in enumerate(config["saved_queries"]):
+        if query["name"] == name:
+            config["saved_queries"][i] = {
+                "name": name,
+                "sql": sql.strip(),
+                "timestamp": timestamp
+            }
+            save_config(config)
+            return config
+    # If not found, add as new query
+    config["saved_queries"].append({
+        "name": name,
+        "sql": sql.strip(),
+        "timestamp": timestamp
+    })
+    save_config(config)
+    return config
+
+
+def save_connection(conn_info: dict) -> dict:
+    """Save a database connection to config."""
+    config = load_config()
+    for i, c in enumerate(config["connections"]):
+        if c["id"] == conn_info["id"]:
+            config["connections"][i] = conn_info
+            save_config(config)
+            return config
+    config["connections"].append(conn_info)
+    save_config(config)
+    return config
+
+
+def delete_connection(conn_id: str) -> dict:
+    """Delete a database connection from config."""
+    config = load_config()
+    config["connections"] = [c for c in config["connections"] if c["id"] != conn_id]
+    save_config(config)
+    return config