duckboard

File-first local SQL workspace for CSV, Parquet, PSV, and JSON — powered by DuckDB.

Load files once, query by name with plain SQL, export results. Terminal-native alternative to spinning up a notebook for quick file questions.

Status: v0.2.0 — data quality milestone. Available on PyPI.

Install

pip install duckboard

Development install:

git clone https://github.com/OmUniyal/duckboard
cd duckboard
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Quickstart

duckboard

duckboard> :load examples/sample.csv as sample
duckboard> SELECT color, COUNT(*) AS n FROM sample GROUP BY 1;
┌────────┬───┐
│ color  │ n │
├────────┼───┤
│ blue   │ 1 │
│ green  │ 1 │
│ red    │ 2 │
└────────┴───┘
(3 rows)
duckboard> :save results.csv
Saved 3 rows to results.csv
duckboard> :quit
Bye.

Supported file formats

REPL commands

Data quality

When a CSV or PSV file is loaded, duckboard automatically validates the first 1,000 rows and reports two types of issues:

Structural errors — rows whose field count doesn't match the header:

duckboard> :load "sales.csv" as sales
Loaded 'sales' from sales.csv  (csv)
  1 validation error(s) found. Run 'SELECT * FROM _errors_sales' to inspect.

Type anomalies — rows where a numeric value appears in a predominantly string column (e.g. a number in a gender column).

All errors are stored in _errors_{name} for the duration of the session:

SELECT * FROM _errors_sales;

The :tables command shows an error indicator for affected tables:

┌────────┬────────┬───────────┬────────┐
│ name   │ format │ path      │ errors │
├────────┼────────┼───────────┼────────┤
│ sales  │ csv    │ sales.csv │ [!1]   │
│ orders │ csv    │ orders.csv│ ok     │
└────────┴────────┴───────────┴────────┘

Notes

• Queries display a maximum of 50 rows in the terminal. Full results are always exported via :save.
• Large exports (2,000+ rows) prompt for confirmation before writing.
• On Windows, use forward slashes in paths: :load data/sales.csv not :load data\sales.csv.
• Multi-line SQL is supported — statements execute on semicolon.
• Validation runs on CSV and PSV files only. Parquet and JSON validation is planned for v0.3.0.

Project layout

src/duckboard/
├── session.py      # DuckboardSession — owns DuckDB connection + state
├── catalog.py      # Registered file → view mappings + validation
├── repl.py         # Interactive REPL loop
├── commands.py     # All REPL commands
├── formatter.py    # Box-drawing table output for query results
├── cli.py          # CLI entry point
└── exceptions.py   # DuckboardError hierarchy

License

MIT