Metadata-Version: 2.4
Name: quacktui
Version: 0.1.4
Summary: TUI for managing DuckLake datalakes
Project-URL: Homepage, https://github.com/arksigma/quacktui
Project-URL: Issues, https://github.com/arksigma/quacktui/issues
Author-email: ArkSigma <hello@arksigma.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: datalake,duckdb,ducklake,lakehouse,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: duckdb<2.0,>=1.5
Requires-Dist: pyarrow<25.0,>=16.0
Requires-Dist: pydantic<3.0,>=2.13
Requires-Dist: pyperclip<2.0,>=1.11
Requires-Dist: python-json-logger<5.0,>=4.1
Requires-Dist: sqlglot<31.0,>=25.0
Requires-Dist: textual-fastdatatable<1.0,>=0.14
Requires-Dist: textual-textarea<1.0,>=0.17
Requires-Dist: textual<7.0,>=6.0
Requires-Dist: tomli-w<2.0,>=1.2
Description-Content-Type: text/markdown

# quacktui

A Python TUI for managing DuckLake datalakes. Browse your catalog, inspect table metadata, run SQL queries, and perform maintenance operations — all from your terminal.

## Install

### With uv (recommended)

```bash
uv tool install quacktui
```

### With pip

```bash
pip install quacktui
```

### From source

```bash
git clone https://github.com/arksigma/quacktui
cd quacktui
uv sync
uv run quacktui
```

### Run it in Docker

A self-contained sandbox image bundles quacktui, an in-container MinIO, and a pre-seeded DuckLake demo catalog:

```bash
./testing/setup.sh                                    # default connection: duckdb-demo
./testing/setup.sh --connection duckdb-demo-readonly  # any quacktui flag passes through
```

When you're done:

```bash
./testing/teardown.sh             # stop + remove container
./testing/teardown.sh --volumes   # also wipe persisted config/history/state
```

MinIO console (optional) at http://localhost:9001 (creds: minioadmin/minioadmin).

`setup.sh` rebuilds the image from your current working tree every run — no PyPI roundtrip, no version pin to bump. Iterate on source, re-run setup, the container has the new code.

## Quickstart

Create a `connections.toml` file in your home directory:

```toml
[[connections]]
name = "demo"
type = "duckdb"
uri = "md:demo"

[connections.storage]
type = "s3"
bucket = "my-data"
endpoint = "http://localhost:9000"
access_key_id = "minioadmin"
secret_access_key = "minioadmin"
```

Then launch quacktui:

```bash
quacktui --connection demo
```

For DuckDB with local files:

```toml
[[connections]]
name = "local"
type = "duckdb"
database = "/path/to/database.duckdb"

[connections.storage]
type = "s3"
bucket = "local-bucket"
endpoint = "http://localhost:9000"
```

## Features

### Catalog Views

Browse and inspect your datalake with eight dedicated views:

- **Schema Browser** — Explore tables and views organized by schema
- **Table Details** — Inspect table structure, columns, constraints, and statistics
- **Snapshot Timeline** — View table snapshot history and retention policies
- **File Inventory** — List all data files backing a table
- **Partition Explorer** — Navigate and manage table partitions
- **Schema Evolution** — Track column additions, renames, and type changes over time
- **Health Dashboard** — Monitor table health, data quality, and maintenance metrics
- **Catalog Database Info** — View version, format configuration, and settings

### Query Editor

Multi-tab SQL editor with the following capabilities:

- Syntax highlighting for SQL and Python
- Schema-aware autocomplete for table and column names
- Query history stored in persistent SQLite
- Saved query snippets for frequent operations
- Result export to CSV, Parquet, JSON, or clipboard
- Multiple concurrent queries with separate result tabs
- Query timeline to review and re-run historical queries

### Maintenance Operations

Perform five critical datalake maintenance tasks, all requiring explicit confirmation:

1. **Compaction** — Consolidate small files into larger files to improve query performance and reduce file count
2. **Expire Snapshots** — Remove old snapshots based on retention policies to free storage
3. **Delete Orphaned Files** — Clean up unreferenced files in S3 storage
4. **Refresh Statistics** — Update table statistics for query optimization
5. **Optimize Manifests** — Reorganize manifest files (version-dependent, available when supported by catalog format)

Destructive operations require pressing Ctrl+Enter to confirm.

### Safety

By default, quacktui operates in read-only mode. Pass the `--allow-writes` flag to enable mutations:

```bash
quacktui --connection demo --allow-writes
```

Without this flag, all write operations are disabled and maintenance ops are grayed out.

## Catalog Backends

quacktui supports the following catalog backends via DuckLake's extension:

- DuckDB (default, embedded)
- PostgreSQL (remote)
- SQLite (file-based)
- MySQL (remote)

Specify the backend in `connections.toml` using the `type` field.

## Storage

In v1, quacktui supports S3 and S3-compatible storage backends:

- AWS S3
- MinIO (local or remote)
- Cloudflare R2
- DigitalOcean Spaces
- Any S3-compatible endpoint

Configure the storage endpoint, bucket, and credentials in the `[connections.storage]` section of `connections.toml`.

## Configuration

Create a `connections.toml` file to define your datalake connections:

```toml
[[connections]]
name = "production"
type = "duckdb"
uri = "md:prod"

[connections.storage]
type = "s3"
bucket = "prod-data"
endpoint = "https://s3.amazonaws.com"
region = "us-east-1"
access_key_id = "YOUR_KEY"
secret_access_key = "YOUR_SECRET"

[[connections]]
name = "staging"
type = "postgresql"
host = "localhost"
port = 5432
database = "datalake"
user = "admin"
password = "secret"

[connections.storage]
type = "s3"
bucket = "staging-data"
endpoint = "http://minio:9000"
```

For more detailed configuration options, see `docs/CONFIGURATION.md`.

## Keybindings

Navigate and control quacktui with these keyboard shortcuts:

| Key | Action |
|-----|--------|
| `Ctrl+P` | Command palette (search and run commands) |
| `Ctrl+T` | Theme switcher (dark/light) |
| `F1` | Help and keybindings |
| `1` / `2` / `3` | Switch between mode tabs (Catalog / Query / Maintenance) |
| `Ctrl+Enter` | Execute SQL query or confirm destructive operation |
| `Ctrl+N` | Open new query tab |
| `Ctrl+W` | Close current tab |
| `Ctrl+R` | Recall query from history |
| `Tab` | Navigate between panes |
| `Up` / `Down` | Navigate lists and history |

## Development

For development and contribution guidelines, see:

- `docs/CONTRIBUTING.md` — How to contribute
- `docs/COMPATIBILITY.md` — Supported versions and compatibility matrix
- `.sisyphus/plans/ducklake-tui.md` — Current implementation status and milestones

## License

Apache License 2.0. See LICENSE for details.
