🦆 OpenDuck

A flat file SQL client based on DuckDB

OpenDuck is a terminal-based flat file SQL client based on DuckDB. 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

Recommended: Install via pip3 from PyPI

pip3 install openduck-cli

Tip: If your system manages Python externally (e.g., Debian/Ubuntu PEP 668), install into a virtual environment or use pipx:

python3 -m venv ~/.openduck-venv
~/.openduck-venv/bin/pip3 install openduck-cli
# Create a symlink to run it from anywhere:
sudo ln -s ~/.openduck-venv/bin/openduck /usr/local/bin/openduck

Via Docker (Zero local setup):

# Run directly with Docker mounting your current data directory:
docker run -it --rm -v "$(pwd):/data" python:3.12-slim sh -c "pip3 install --no-cache-dir openduck-cli && openduck"

# Or build the included Dockerfile:
docker build -t openduck .
docker run -it --rm -v "$(pwd):/data" openduck

From source:

git clone https://github.com/klandermans/openduck.git
cd openduck
pip3 install -r requirements.txt
# or install in editable mode:
pip3 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

After installing with pip3, run it directly from any directory:

openduck

(or openduck-cli)

If you cloned the source repository:

python3 openduck.py
# or
python3 -m openduck
# or with the shell wrapper:
./openduck.sh

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