🦆 OpenDuck

The Modern, Lightning-Fast Terminal SQL IDE & Data Explorer for DuckDB

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:

🚀 Quickstart

1. Installation

Via PyPI:

pip install openduck-cli

From source:

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

python openduck.py

Or make it available system-wide as a command:

chmod +x openduck.sh
sudo cp openduck.sh /usr/local/bin/openduck
openduck

⌨️ Keyboard & Mouse Shortcuts

⚙️ 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.

{
  "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

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.