DuckLocal

ducklocal.app · Docs · 中文文档

A local-first workspace for querying and exploring your data, built natively on DuckDB. Point it at your files — no connection to configure, no schema to create, nothing uploaded.

Open your data

ducklocal ./logs/             # every data file under a folder, recursively
ducklocal ./billing.parquet   # one file
ducklocal './data/*.csv'      # a pattern
ducklocal warehouse.duckdb    # or an existing DuckDB database

CSV, TSV, Parquet, JSON, and Excel files are queryable as soon as the window opens. You can also drag them onto the window or pick them from the file dialog; the workspace is remembered for the next launch.

Your data stays on your machine, and there is no account. The only optional network use is the OpenStreetMap base map for map charts (View → Online base map, off by default), the update check, which downloads a newer release from dl.ducklocal.app and installs it on restart (a click on the version in the status bar, or DuckLocal → Check for Updates at Launch, off by default), S3 when you configure it, extensions you install, and SQL that names a remote address. There is no telemetry. Network and privacy lists every path and how to verify it.

Features

SQL Editor

• Syntax highlighting, autocompletion, and formatting
• Multiple tabs for concurrent queries
• Run with Cmd+Enter (macOS) or Ctrl+Enter (Windows/Linux)
• Query inspection with EXPLAIN and performance profiling with EXPLAIN ANALYZE

Data Exploration

• Schema sidebar: browse tables/columns, generate SELECT statements, modify column types
• Results grid: filtering, copy, CSV/Parquet export, and built-in visualization
• Overview tab: column statistics (nulls, distinct values, range, distribution)
• Extensions tab: manage DuckDB extensions (list, install, load, update)
• Query history: recall and rerun previous queries

Dashboards

Define .dash files with:

• Charts: line, bar, stacked bar, area, scatter, pie, heatmap, histogram, and map plots
• Components: tables, metric cards with notes and tones, and text panels
• Number formats for money, shares and fixed places (format = "usd", "pct1", "num2")
• Interactive cross-filtering

Platform Integration (macOS)

• Double-click to open Parquet and DuckDB files from Finder
• Quick Look previews for Parquet, DuckDB, CSV, TSV, and JSON Lines

Error Handling & Diagnostics

• Clear error messages when database files won't open (wrong version, old format, SQLite)
• Status bar shows DuckDB version compatibility info

User Experience

• Light and dark themes
• Four interface size options
• Available in English and 简体中文
• S3 support via httpfs (session-only credentials)

CLI for agents

The same binary works headless and returns structured JSON, so an AI agent can explore data without a window:

ducklocal schema ./data/                                  # what can be queried, with columns
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal check dashboard.dash                            # validate a dashboard spec
ducklocal propose dashboard.dash --from new.dash          # suggest a change for a person to review
ducklocal session show                                    # how an analysis got here, and what no longer holds
ducklocal open --run --sql "SELECT ..."                   # hand a result to the running window
ducklocal open --state                                    # read back what the window shows
ducklocal project check                                   # will this analysis folder work here, and if not, why

A worked investigation walks a made-up CloudTrail incident from first query to reviewed dashboard.

Database files open read-only unless you pass --read-write. See the CLI guide for every command and option, and the handoff contract for how an agent stays in step with the window.

SQL you did not write yourself should run with query --restricted --allow-read PATH, and a dashboard you did not write with check --restricted --allow-read PATH: DuckDB then refuses other files, the network, extensions and writes. It is not an OS sandbox; see what it does and doesn't limit.

The official agent skill teaches schema-first exploration, SQL analysis, and file conversion. Copy it into your project:

mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/

Documentation

Guides, a tutorial, and troubleshooting are at ducklocal.app/docs (source: JetSquirrel/ducklocal-site).

Development

cargo run                     # start with an empty workspace
cargo run -- ./data/logs/     # or open something straight away
./scripts/bundle.sh           # build target/release/DuckLocal.app (unsigned)

Release packaging supports macOS 12+ on Apple silicon, Linux x86_64 and Windows x86_64; scripts/package-macos.sh builds the signed, notarized dmg. See development.

Windows

cargo build --release --locked
python scripts/check-windows.py target/release/ducklocal.exe

The executable opens the GUI without a console window and embeds the duck icon for Explorer and the taskbar. CLI commands attach to the caller's console while preserving redirected stdin/stdout/stderr and LSP pipes. In PowerShell, use Start-Process -Wait -PassThru when waiting for an exit code, or a pipeline to capture JSON, e.g. ./ducklocal.exe query --sql "SELECT 42" | Out-String.

For a size-oriented build, use cargo build --profile compact --locked (target/compact/ducklocal.exe). Rust uses size optimization while DuckDB's C++ engine keeps optimization level 3; both profiles retain LTO and symbol stripping. Compare actual size and performance on the target machine; the normal release stays optimized for speed.

Regenerate the committed Windows icon with python scripts/make-icons.py --windows (Pillow required). Normal builds need no Python or Pillow; MSVC builds need the Visual Studio C++ tools and Windows SDK. Run cargo test --release perf_g_ -- --nocapture --test-threads=1 to compare category-chart allocations, and perf_h_ for long-text column fitting.

License

Apache-2.0 · Copyright © 2026 JetSquirrel