sqlexplore

sqlexplore is a terminal SQL explorer for flat files (.csv, .tsv, .txt, .parquet, .pq), powered by DuckDB.

Use it when you need quick answers from local files, URLs, or piped terminal output without building a separate pipeline first.

Useful features

• Interactive TUI with query editor, results grid, cell preview, and activity log.
• Non-interactive mode (--no-ui) for one-shot queries in plain terminal output.
• SQL helper commands for common analysis and shaping tasks: /summary, /describe, /profile, /hist, /corr, /top, /dupes, /crosstab, /sample, /filter, /sort, /group, /agg.
• LLM-assisted SQL generation with /llm-query, plus trace tools (/llm-history, /llm-show).
• Query history and rerun helpers (/history, /rerun, /history-log, /rerun-log).
• Context-aware autocomplete for SQL and helper commands.
• Result export via /save to .csv, .parquet/.pq, or .json.
• JSON-aware table rendering and preview, including compact image-cell tokens for image-like values.
• Local files, HTTP(S) URLs, and stdin input (for piped text).
• Multiple sources via repeated --data (schemas must match; sources are unioned).
• Remote download cache controls with --download-dir and --overwrite.
• .txt input support with derived fields like line_number, line_length, word_count, and line_hash.

Run with uvx (preferred)

Requires Python 3.13+.

Run directly without a manual install:

uvx sqlexplore --data my_data.parquet

Equivalent explicit form:

uvx --from sqlexplore sqlexplore --data my_data.parquet

Run one query and exit:

uvx sqlexplore --data https://github.com/dylanhogg/awesome-python/raw/refs/heads/main/github_data.parquet --execute "SELECT COUNT(*) AS n FROM data" --no-ui

Run SQL from file and exit:

uvx sqlexplore --data https://github.com/dylanhogg/awesome-python/raw/refs/heads/main/github_data.parquet --file ./queries/report.sql --no-ui

Use multiple inputs:

uvx sqlexplore --data ./data/january.parquet --data ./data/february.parquet

Analyze piped terminal text:

ls -lha | uvx sqlexplore

Open remote data (downloaded then loaded):

uvx sqlexplore --data https://github.com/dylanhogg/awesome-python/raw/refs/heads/main/github_data.parquet

Install with pip

pip install sqlexplore
sqlexplore --data https://github.com/dylanhogg/awesome-python/raw/refs/heads/main/github_data.parquet

LLM usage (optional)

Set an API key for your chosen LiteLLM provider (for example OPENAI_API_KEY), then run:

/llm-query top 10 customers by total revenue

Optional model override:

export SQLEXPLORE_LLM_MODEL=openai/gpt-5-mini

Notes

• --data can be omitted when piping stdin.
• If stdin has no controlling TTY, sqlexplore falls back to --no-ui.
• --limit sets default helper query limit. /limit also updates row display limit.
• Logs are written to sqlexplore.log in your app log directory (with fallbacks).
• Run sqlexplore --help to view all options.

Links

• GitHub
• PyPI