Metadata-Version: 2.4
Name: sqlexplore
Version: 0.3.0
Summary: SQL exploration over data files with your CLI
Author: Dylan Hogg
License-Expression: MIT
Project-URL: Homepage, https://github.com/dylanhogg/sqlexplore
Project-URL: Repository, https://github.com/dylanhogg/sqlexplore
Project-URL: Issues, https://github.com/dylanhogg/sqlexplore/issues
Keywords: sql,duckdb,cli,tui,csv,parquet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Environment :: Console
Classifier: Topic :: Database
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=1.4.4
Requires-Dist: rich>=14.0.0
Requires-Dist: sqlglot>=26.0.0
Requires-Dist: textual>=7.5.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: typer>=0.21.1
Dynamic: license-file

# sqlexplore

SQL exploration over data files with your CLI

Currently in development (Feb 2026).

## Install

Requires Python 3.13+.

```bash
pip install sqlexplore
```

Optional (`uv` tool install):

```bash
uv tool install sqlexplore
```

## Usage

Local file:

```bash
sqlexplore ./data/example.parquet
```

Remote file URL:

```bash
sqlexplore https://example.com/data_file.csv
```

Show version:

```bash
sqlexplore --version
```

Remote URL behavior:

- Supports `http://` and `https://` URLs ending in `.csv`, `.tsv`, `.parquet`, or `.pq`.
- Downloads to `<app-user-dir>/downloads/<filename>` by default.
- Use `--download-dir /your/path` to override the download location.
- If local download target already exists, prints warning and exits (no overwrite by default). Use `--overwrite` to replace it.
- Logs download details before normal app flow: remote/local path, progress, elapsed time, and file size.
- In TUI mode, the Activity pane shows app version on load, then startup download log lines (if any).

Result formatting:

- JSON syntax highlighting is auto-applied for `VARCHAR`/text columns when sampled values look like JSON objects/arrays.
- Detection samples only a few visible rows (not full columns) to keep rendering fast.
- Highlighting is disabled when query result row count is over `100,000`.

Autocomplete behavior:

- Completions auto-open from engine context for SQL clauses and helper command arguments (for example `SELECT ` and `/top `).
- `Up/Down` navigates the completion menu whenever it is visible.
- `Tab` accepts the selected completion when the menu is visible; otherwise it inserts editor indentation.
- `Esc` closes the completion menu.
- `Ctrl+Space` opens completion mode explicitly.

## Known limitations

- Python 3.12 and below are not supported.
- Remote downloads only support `.csv`, `.tsv`, `.parquet`, `.pq`.

## Links

- https://github.com/dylanhogg/sqlexplore
- https://pypi.org/project/sqlexplore/
