cheshire-sql

Name	cheshire-sql JSON
Version	0.1.1 JSON
	download
home_page	https://github.com/yourusername/cheshire
Summary	Terminal-based SQL visualization tool that transforms query results into beautiful ANSI charts
upload_time	2025-08-09 00:00:57
maintainer	None
docs_url	None
author	Cheshire Team
requires_python	>=3.8
license	MIT License Copyright (c) 2025 Ryan Robitaille Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	sql visualization terminal charts database duckdb cli
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Cheshire

Simple terminal-based SQL visualization tool - turn SQL into ANSI charts, maps, tables, and more. Analyze your data and browse the results in a builder UI, and then copy and paste the command to use in your shell scripts, etc. Build an easy auto-refreshing dashboard out of TMUX panels, etc. Unhide your data from the terminal.

> “Well! I've often seen a cat without a grin,' thought Alice 'but a grin without a cat! It's the most curious thing i ever saw in my life!”

![Alt text](https://raw.githubusercontent.com/ryrobes/cheshire/refs/heads/main/cheshire_snap1.jpg "We're all mad here.")

## Features

### Multiple Data Sources
- **DuckDB** - Primary SQL engine with extensive format support
- **SQLite** - Direct database file queries
- **PostgreSQL** - Via DuckDB postgres_scanner extension
- **MySQL** - Via DuckDB mysql_scanner extension
- **Clickhouse** - Via clickhouse_driver
- **osquery** - System statistics as SQL (processes, network, hardware) **if installed
- **CSV/TSV Files** - Query delimited files directly with SQL
- **Parquet Files** - Analyze single files or entire directories
- **JSON Input** - Pipe JSON arrays directly and query with SQL
- **Remote Databases** - Connect to external SQL servers
- **HTTP(s) DB Files** - Web served Parquet, CSV, TSV

### ANSI Visualizations
- **Charts**: Bar, line, scatter, histogram, pie, waffle, and more
- **Geographic Maps**: Point maps, heatmaps, density maps, cluster maps
- **Tables**: Rich formatted tables with colors and styling
- **Figlet**: Large ASCII art text for KPI callouts
- **Matrix Heatmaps**: 2D data visualization with color gradients
- **Termgraph Charts**: Alternative chart renderer with calendar heatmaps

### Chart 'Suggestions'
- **Sniff Database**: Generate a number of basic charts of all kinds based on your data
- **Browse and Modify**: Look through the suggestions to use or adapt

### Powerful Features
- **Interactive TUI**: Browse databases, preview queries, select charts
- **Live Refresh**: Auto-refresh charts at specified intervals
- **Smart Analysis**: Search your database and suggest appropriate charts
- **Multiple Databases**: Configure and switch between multiple data sources
- **Export Support**: Save visualizations or pipe to other tools

![Alt text](https://raw.githubusercontent.com/ryrobes/cheshire/refs/heads/main/cheshire_snap2.jpg "We're all mad here.")
(optional interactive CLI builder)

## Installation

```bash
pip install cheshire-sql
```

## Quick Start

### Basic Usage

```bash
# Launch interactive TUI mode
cheshire

# Simple bar chart from SQLite
cheshire "SELECT product as x, SUM(sales) as y FROM sales GROUP BY product" bar --db sales.db

# Line chart with live refresh every 5 seconds
cheshire "SELECT time as x, cpu_usage as y FROM metrics ORDER BY time" line 5s --db metrics.db

# Geographic map from latitude/longitude data
cheshire "SELECT latitude as lat, longitude as lon FROM locations" map --db geo.db
```

### Working with Files

```bash
# Query CSV files directly
cheshire "SELECT * FROM data WHERE sales > 1000" bar --csv sales.csv

# Analyze TSV file and generate suggestions for the TUI to browse
cheshire --sniff --tsv data.tsv

# Query Parquet files or folders
cheshire "SELECT category as x, AVG(price) as y FROM data GROUP BY category" bar --parquet /path/to/parquet/
```

### Working with Remote Files (HTTP/HTTPS)

DuckDB can directly query files from HTTP/HTTPS URLs - perfect for demo data and shared datasets:

```bash
# Query remote Parquet file (most efficient format)
cheshire "SELECT int_col as x, COUNT(*) as y FROM data GROUP BY int_col ORDER BY int_col LIMIT 20" bar \
  --http "https://github.com/apache/parquet-testing/raw/master/data/alltypes_plain.parquet"

# Query remote CSV file
cheshire "SELECT species as x, COUNT(*) as y FROM data GROUP BY species" pie \
  --http "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv"

# Analyze remote dataset and generate chart suggestions
cheshire --sniff --http "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/titanic.csv"

# NYC Taxi trip analysis
cheshire "SELECT payment_type as x, AVG(total_amount) as y FROM data GROUP BY payment_type" bar \
  --http "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet" \
  --title "Average Fare by Payment Type"

# Live COVID-19 data from Our World in Data (CSV)
cheshire "SELECT location as x, MAX(total_cases) as y FROM data WHERE continent='Europe' GROUP BY location ORDER BY y DESC LIMIT 10" bar \
  --http "https://covid.ourworldindata.org/data/owid-covid-data.csv"
```

### Demo Datasets

Here are some publicly available datasets perfect for testing Cheshire:

#### Parquet Files (Recommended - Fast & Efficient)
- **NYC Taxi Data**: `https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet`
- **Apache Test Data**: `https://github.com/apache/parquet-testing/raw/master/data/alltypes_plain.parquet`

#### CSV Files
- **Iris Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv`
- **Titanic Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/titanic.csv`
- **COVID-19 Data**: `https://covid.ourworldindata.org/data/owid-covid-data.csv`
- **Flights Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/flights.csv`
- **Tips Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv`

#### Example Queries for Demo Data

```bash
# Titanic survival analysis
cheshire "SELECT sex as x, AVG(survived)*100 as y FROM data GROUP BY sex" bar \
  --http "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/titanic.csv" \
  --title "Titanic Survival Rate by Gender (%)"

# Iris species distribution
cheshire "SELECT species as x, AVG(petal_length) as y, species as color FROM data GROUP BY species" bar \
  --http "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv" \
  --title "Average Petal Length by Species"

# Monthly flight passengers over time
cheshire "SELECT year || '-' || month as x, passengers as y FROM data ORDER BY year, month" line \
  --http "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/flights.csv" \
  --title "Monthly Flight Passengers"
```

### Working with JSON Data

```bash
# Pipe JSON data directly into Cheshire
echo '[{"name": "Alice", "score": 90}, {"name": "Bob", "score": 85}]' | \
  cheshire "SELECT name as x, score as y FROM data" bar

# Read JSON from a file
cat sales.json | cheshire "SELECT product as x, SUM(amount) as y FROM data GROUP BY product" bar

# Use explicit --json-input flag
curl -s https://api.example.com/data | \
  cheshire "SELECT * FROM data WHERE value > 100" json --json-input

# Aggregate JSON data
echo '[
  {"category": "A", "value": 10},
  {"category": "B", "value": 20},
  {"category": "A", "value": 15}
]' | cheshire "SELECT category as x, SUM(value) as y FROM data GROUP BY category" pie

# Complex queries on JSON data
cat events.json | cheshire "
  SELECT 
    DATE(timestamp) as x,
    COUNT(*) as y 
  FROM data 
  WHERE status = 'success'
  GROUP BY DATE(timestamp)
  ORDER BY x
" line
```

### System Monitoring with osquery

```bash
# View running processes
cheshire "SELECT name as x, resident_size/1024/1024 as y FROM processes ORDER BY y DESC LIMIT 10" bar --database osquery

# Monitor CPU usage by process
cheshire "SELECT name as x, user_time + system_time as y FROM processes ORDER BY y DESC LIMIT 10" bar 5s --database osquery
```

## Configuration

Create a `cheshire.yaml` file to configure databases and defaults:

```yaml
databases:
  sales:
    type: duckdb
    path: /path/to/sales.db
  
  metrics:
    type: sqlite
    path: /path/to/metrics.db
  
  postgres_prod:
    type: postgres
    host: localhost
    port: 5432
    database: production
    user: readonly
    password: secret
  
  osquery:
    type: osquery  # Auto-detected if osqueryi is installed

default_database: sales

chart_defaults:
  theme: matrix
  markers: braille
  width: null  # Auto-detect
  height: null  # Auto-detect
```

## Chart Types

### Plotext Charts (Default)
Plotext is the primary charting library, providing colorful ANSI charts:
- `bar` - Vertical bar chart (automatically stacks when color column provided)
- `line` - Line chart with optional markers
- `scatter` - Scatter plot with various marker styles
- `histogram` - Distribution histogram
- `braille` - Braille character scatter plot (high resolution)
- `box` - Box plot for statistical distributions
- `simple_bar` - Simplified bar chart
- `multiple_bar` - Multiple bar series side-by-side
- `stacked_bar` - Explicitly stacked bar chart

### Custom Implementations
These are custom-built visualizations unique to Cheshire:
- `pie` - Pie chart with percentages (custom implementation)
- `waffle` - Waffle/square chart for proportions (custom implementation)
- `matrix_heatmap` - 2D matrix visualization with color gradients (custom implementation)

### Geographic Maps (Custom)
Custom map renderer for geographic data (requires lat/lon columns):
- `map` or `map_points` - Point map with Braille characters
- `map_blocks` - Block-based point map
- `map_density` - Density heatmap overlay
- `map_clusters` - Clustered point aggregation
- `map_heatmap` - Geographic heatmap with color gradients
- `map_blocks_heatmap` - True color block heatmap
- `map_braille_heatmap` - Braille character heatmap

### Termgraph Charts
Alternative chart renderer using the termgraph library:
- `tg_bar` - Horizontal bar chart
- `tg_hbar` - Horizontal bar variant
- `tg_multi` - Multi-series bar chart
- `tg_stacked` - Stacked bar chart
- `tg_histogram` - Histogram with customizable bins
- `tg_calendar` - Calendar heatmap for time series data

### Tables and Text
- `rich_table` - Formatted table with colors (uses Rich library)
- `figlet` - Large ASCII art text for KPIs (uses pyfiglet library)
- `json` - Raw JSON output of query results (built-in)

## SQL Query Format

Queries must return specific column names depending on the chart type:

### Standard Charts
```sql
SELECT 
  category as x,      -- X-axis values
  SUM(amount) as y,   -- Y-axis values
  status as color     -- Optional: color grouping
FROM sales
GROUP BY category, status
```

### Geographic Maps
```sql
SELECT 
  latitude as lat,    -- Latitude
  longitude as lon,   -- Longitude
  sales as value      -- Optional: heat value
FROM store_locations
```

### Pie/Waffle Charts
```sql
SELECT 
  category as x,      -- Category labels
  COUNT(*) as y       -- Values
FROM products
GROUP BY category
```

## Advanced Features

### Live Refresh
Add an interval to auto-refresh charts:
```bash
cheshire "SELECT ..." bar 5s    # Refresh every 5 seconds
cheshire "SELECT ..." line 1m    # Refresh every minute
cheshire "SELECT ..." scatter 0.5h  # Refresh every 30 minutes
```

### Database Analysis
Analyze a database to generate chart suggestions:
```bash
# Analyze configured database
cheshire --sniff --database sales

# Analyze SQLite file
cheshire --sniff --db mydata.db

# Analyze CSV file
cheshire --sniff --csv data.csv

# Analyze Parquet folder
cheshire --sniff --parquet /data/parquet/
```

### Chart Size Control
```bash
# Set explicit width and height in characters
cheshire "SELECT ..." bar --width 60 --height 20

# Use percentage of terminal size
cheshire "SELECT ..." line --width "80%" --height "50%"

# Mix absolute and percentage
cheshire "SELECT ..." scatter --width "75%" --height 15

# Small inline charts
cheshire "SELECT ..." bar --width 40 --height 8
```

### Color Customization
```bash
# Named colors
cheshire "SELECT ..." bar --color red

# Hex colors
cheshire "SELECT ..." line --color "#FF5733"

# Themes
cheshire "SELECT ..." scatter --theme matrix
```

### Script-Friendly Output
```bash
# Don't clear terminal before rendering (useful for scripts/logs)
cheshire "SELECT ..." bar --no-clear

# Capture output in scripts without terminal clearing
echo "=== Sales Report ===" >> report.log
cheshire "SELECT product as x, SUM(sales) as y FROM data GROUP BY 1" bar --no-clear >> report.log

# Build dashboards with multiple charts
cheshire "SELECT ..." pie --no-clear
cheshire "SELECT ..." bar --no-clear
cheshire "SELECT ..." line --no-clear
```

## Interactive TUI Mode

Launch without arguments to enter the interactive TUI:

```bash
cheshire
```

Features:
- Database browser with table listings
- SQL query editor with syntax highlighting
- Live preview of query results
- Chart type selector with recommendations
- Keyboard navigation and shortcuts

### TUI Keyboard Shortcuts
- `Tab` - Switch between panels
- `Enter` - Execute query/select item
- `Esc` - Exit/cancel
- `Ctrl+Q` - Quit application
- `Ctrl+C` - Copy current chart's CLI

## Examples

### Sales Dashboard
```bash
# Top products by revenue
cheshire "SELECT product as x, SUM(revenue) as y FROM sales GROUP BY product ORDER BY y DESC LIMIT 10" bar --db sales.db

# Sales trend over time
cheshire "SELECT DATE(order_date) as x, SUM(amount) as y FROM orders GROUP BY 1 ORDER BY 1" line --db sales.db

# Geographic distribution
cheshire "SELECT store_lat as lat, store_lon as lon, SUM(sales) as value FROM stores GROUP BY lat, lon" map_heatmap --db sales.db
```

### System Monitoring
```bash
# Memory usage by process
cheshire "SELECT name as x, resident_size/1024/1024 as y FROM processes WHERE resident_size > 0 ORDER BY y DESC LIMIT 15" bar --database osquery

# Network connections
cheshire "SELECT remote_address as x, COUNT(*) as y FROM process_open_sockets GROUP BY remote_address ORDER BY y DESC LIMIT 10" bar --database osquery

# CPU time distribution
cheshire "SELECT name as x, (user_time + system_time) as y FROM processes ORDER BY y DESC LIMIT 20" pie --database osquery
```

### Data Analysis
```bash
# Analyze CSV and view suggestions
cheshire --sniff --csv sales_data.csv

# Query Parquet files with complex aggregations
cheshire "WITH monthly AS (SELECT DATE_TRUNC('month', date) as month, SUM(sales) as total FROM data GROUP BY 1) SELECT month as x, total as y FROM monthly ORDER BY month" line --parquet /data/

# Join multiple data sources using DuckDB
cheshire "SELECT c.name as x, SUM(s.amount) as y FROM read_csv_auto('customers.csv') c JOIN sales s ON c.id = s.customer_id GROUP BY c.name" bar --db sales.db

# Export query results as JSON for further processing
cheshire "SELECT * FROM sales WHERE date >= '2024-01-01'" json --db sales.db > sales_2024.json
```

## Troubleshooting

### Common Issues

**No color output**: Force color mode with environment variable:
```bash
FORCE_COLOR=1 cheshire "SELECT ..." bar
```

**Database not found**: Check file path or configure in cheshire.yaml:
```bash
cheshire --list-databases  # Show configured databases
```

**osquery not detected**: Ensure osqueryi is installed and in PATH:
```bash
which osqueryi  # Should show path to osqueryi
```

**Chart too large/small**: Adjust terminal size or set explicit dimensions:
```yaml
# In cheshire.yaml
chart_defaults:
  width: 80
  height: 24
```

![Alt text](https://raw.githubusercontent.com/ryrobes/cheshire/refs/heads/main/cheshire_snap0.jpg "We're all mad here.")

## License

MIT License - See LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## Acknowledgments

Built with amazing open-source libraries including DuckDB, plotext, Rich, and many others.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/yourusername/cheshire",
    "name": "cheshire-sql",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "sql, visualization, terminal, charts, database, duckdb, cli",
    "author": "Cheshire Team",
    "author_email": "Ryan Robitaille <ryan.robitaille@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/44/7f/96beafcd336618cb5aa1eb2f3583c50e36a9df8dcbd16dabf3a7b03d673e/cheshire_sql-0.1.1.tar.gz",
    "platform": null,
    "description": "# Cheshire\n\nSimple terminal-based SQL visualization tool - turn SQL into ANSI charts, maps, tables, and more. Analyze your data and browse the results in a builder UI, and then copy and paste the command to use in your shell scripts, etc. Build an easy auto-refreshing dashboard out of TMUX panels, etc. Unhide your data from the terminal.\n\n> \u201cWell! I've often seen a cat without a grin,' thought Alice 'but a grin without a cat! It's the most curious thing i ever saw in my life!\u201d\n\n![Alt text](https://raw.githubusercontent.com/ryrobes/cheshire/refs/heads/main/cheshire_snap1.jpg \"We're all mad here.\")\n\n## Features\n\n### Multiple Data Sources\n- **DuckDB** - Primary SQL engine with extensive format support\n- **SQLite** - Direct database file queries\n- **PostgreSQL** - Via DuckDB postgres_scanner extension\n- **MySQL** - Via DuckDB mysql_scanner extension\n- **Clickhouse** - Via clickhouse_driver\n- **osquery** - System statistics as SQL (processes, network, hardware) **if installed\n- **CSV/TSV Files** - Query delimited files directly with SQL\n- **Parquet Files** - Analyze single files or entire directories\n- **JSON Input** - Pipe JSON arrays directly and query with SQL\n- **Remote Databases** - Connect to external SQL servers\n- **HTTP(s) DB Files** - Web served Parquet, CSV, TSV\n\n### ANSI Visualizations\n- **Charts**: Bar, line, scatter, histogram, pie, waffle, and more\n- **Geographic Maps**: Point maps, heatmaps, density maps, cluster maps\n- **Tables**: Rich formatted tables with colors and styling\n- **Figlet**: Large ASCII art text for KPI callouts\n- **Matrix Heatmaps**: 2D data visualization with color gradients\n- **Termgraph Charts**: Alternative chart renderer with calendar heatmaps\n\n### Chart 'Suggestions'\n- **Sniff Database**: Generate a number of basic charts of all kinds based on your data\n- **Browse and Modify**: Look through the suggestions to use or adapt\n\n### Powerful Features\n- **Interactive TUI**: Browse databases, preview queries, select charts\n- **Live Refresh**: Auto-refresh charts at specified intervals\n- **Smart Analysis**: Search your database and suggest appropriate charts\n- **Multiple Databases**: Configure and switch between multiple data sources\n- **Export Support**: Save visualizations or pipe to other tools\n\n![Alt text](https://raw.githubusercontent.com/ryrobes/cheshire/refs/heads/main/cheshire_snap2.jpg \"We're all mad here.\")\n(optional interactive CLI builder)\n\n## Installation\n\n```bash\npip install cheshire-sql\n```\n\n## Quick Start\n\n### Basic Usage\n\n```bash\n# Launch interactive TUI mode\ncheshire\n\n# Simple bar chart from SQLite\ncheshire \"SELECT product as x, SUM(sales) as y FROM sales GROUP BY product\" bar --db sales.db\n\n# Line chart with live refresh every 5 seconds\ncheshire \"SELECT time as x, cpu_usage as y FROM metrics ORDER BY time\" line 5s --db metrics.db\n\n# Geographic map from latitude/longitude data\ncheshire \"SELECT latitude as lat, longitude as lon FROM locations\" map --db geo.db\n```\n\n### Working with Files\n\n```bash\n# Query CSV files directly\ncheshire \"SELECT * FROM data WHERE sales > 1000\" bar --csv sales.csv\n\n# Analyze TSV file and generate suggestions for the TUI to browse\ncheshire --sniff --tsv data.tsv\n\n# Query Parquet files or folders\ncheshire \"SELECT category as x, AVG(price) as y FROM data GROUP BY category\" bar --parquet /path/to/parquet/\n```\n\n### Working with Remote Files (HTTP/HTTPS)\n\nDuckDB can directly query files from HTTP/HTTPS URLs - perfect for demo data and shared datasets:\n\n```bash\n# Query remote Parquet file (most efficient format)\ncheshire \"SELECT int_col as x, COUNT(*) as y FROM data GROUP BY int_col ORDER BY int_col LIMIT 20\" bar \\\n  --http \"https://github.com/apache/parquet-testing/raw/master/data/alltypes_plain.parquet\"\n\n# Query remote CSV file\ncheshire \"SELECT species as x, COUNT(*) as y FROM data GROUP BY species\" pie \\\n  --http \"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv\"\n\n# Analyze remote dataset and generate chart suggestions\ncheshire --sniff --http \"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/titanic.csv\"\n\n# NYC Taxi trip analysis\ncheshire \"SELECT payment_type as x, AVG(total_amount) as y FROM data GROUP BY payment_type\" bar \\\n  --http \"https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet\" \\\n  --title \"Average Fare by Payment Type\"\n\n# Live COVID-19 data from Our World in Data (CSV)\ncheshire \"SELECT location as x, MAX(total_cases) as y FROM data WHERE continent='Europe' GROUP BY location ORDER BY y DESC LIMIT 10\" bar \\\n  --http \"https://covid.ourworldindata.org/data/owid-covid-data.csv\"\n```\n\n### Demo Datasets\n\nHere are some publicly available datasets perfect for testing Cheshire:\n\n#### Parquet Files (Recommended - Fast & Efficient)\n- **NYC Taxi Data**: `https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet`\n- **Apache Test Data**: `https://github.com/apache/parquet-testing/raw/master/data/alltypes_plain.parquet`\n\n#### CSV Files\n- **Iris Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv`\n- **Titanic Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/titanic.csv`\n- **COVID-19 Data**: `https://covid.ourworldindata.org/data/owid-covid-data.csv`\n- **Flights Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/flights.csv`\n- **Tips Dataset**: `https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv`\n\n#### Example Queries for Demo Data\n\n```bash\n# Titanic survival analysis\ncheshire \"SELECT sex as x, AVG(survived)*100 as y FROM data GROUP BY sex\" bar \\\n  --http \"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/titanic.csv\" \\\n  --title \"Titanic Survival Rate by Gender (%)\"\n\n# Iris species distribution\ncheshire \"SELECT species as x, AVG(petal_length) as y, species as color FROM data GROUP BY species\" bar \\\n  --http \"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv\" \\\n  --title \"Average Petal Length by Species\"\n\n# Monthly flight passengers over time\ncheshire \"SELECT year || '-' || month as x, passengers as y FROM data ORDER BY year, month\" line \\\n  --http \"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/flights.csv\" \\\n  --title \"Monthly Flight Passengers\"\n```\n\n### Working with JSON Data\n\n```bash\n# Pipe JSON data directly into Cheshire\necho '[{\"name\": \"Alice\", \"score\": 90}, {\"name\": \"Bob\", \"score\": 85}]' | \\\n  cheshire \"SELECT name as x, score as y FROM data\" bar\n\n# Read JSON from a file\ncat sales.json | cheshire \"SELECT product as x, SUM(amount) as y FROM data GROUP BY product\" bar\n\n# Use explicit --json-input flag\ncurl -s https://api.example.com/data | \\\n  cheshire \"SELECT * FROM data WHERE value > 100\" json --json-input\n\n# Aggregate JSON data\necho '[\n  {\"category\": \"A\", \"value\": 10},\n  {\"category\": \"B\", \"value\": 20},\n  {\"category\": \"A\", \"value\": 15}\n]' | cheshire \"SELECT category as x, SUM(value) as y FROM data GROUP BY category\" pie\n\n# Complex queries on JSON data\ncat events.json | cheshire \"\n  SELECT \n    DATE(timestamp) as x,\n    COUNT(*) as y \n  FROM data \n  WHERE status = 'success'\n  GROUP BY DATE(timestamp)\n  ORDER BY x\n\" line\n```\n\n### System Monitoring with osquery\n\n```bash\n# View running processes\ncheshire \"SELECT name as x, resident_size/1024/1024 as y FROM processes ORDER BY y DESC LIMIT 10\" bar --database osquery\n\n# Monitor CPU usage by process\ncheshire \"SELECT name as x, user_time + system_time as y FROM processes ORDER BY y DESC LIMIT 10\" bar 5s --database osquery\n```\n\n## Configuration\n\nCreate a `cheshire.yaml` file to configure databases and defaults:\n\n```yaml\ndatabases:\n  sales:\n    type: duckdb\n    path: /path/to/sales.db\n  \n  metrics:\n    type: sqlite\n    path: /path/to/metrics.db\n  \n  postgres_prod:\n    type: postgres\n    host: localhost\n    port: 5432\n    database: production\n    user: readonly\n    password: secret\n  \n  osquery:\n    type: osquery  # Auto-detected if osqueryi is installed\n\ndefault_database: sales\n\nchart_defaults:\n  theme: matrix\n  markers: braille\n  width: null  # Auto-detect\n  height: null  # Auto-detect\n```\n\n## Chart Types\n\n### Plotext Charts (Default)\nPlotext is the primary charting library, providing colorful ANSI charts:\n- `bar` - Vertical bar chart (automatically stacks when color column provided)\n- `line` - Line chart with optional markers\n- `scatter` - Scatter plot with various marker styles\n- `histogram` - Distribution histogram\n- `braille` - Braille character scatter plot (high resolution)\n- `box` - Box plot for statistical distributions\n- `simple_bar` - Simplified bar chart\n- `multiple_bar` - Multiple bar series side-by-side\n- `stacked_bar` - Explicitly stacked bar chart\n\n### Custom Implementations\nThese are custom-built visualizations unique to Cheshire:\n- `pie` - Pie chart with percentages (custom implementation)\n- `waffle` - Waffle/square chart for proportions (custom implementation)\n- `matrix_heatmap` - 2D matrix visualization with color gradients (custom implementation)\n\n### Geographic Maps (Custom)\nCustom map renderer for geographic data (requires lat/lon columns):\n- `map` or `map_points` - Point map with Braille characters\n- `map_blocks` - Block-based point map\n- `map_density` - Density heatmap overlay\n- `map_clusters` - Clustered point aggregation\n- `map_heatmap` - Geographic heatmap with color gradients\n- `map_blocks_heatmap` - True color block heatmap\n- `map_braille_heatmap` - Braille character heatmap\n\n### Termgraph Charts\nAlternative chart renderer using the termgraph library:\n- `tg_bar` - Horizontal bar chart\n- `tg_hbar` - Horizontal bar variant\n- `tg_multi` - Multi-series bar chart\n- `tg_stacked` - Stacked bar chart\n- `tg_histogram` - Histogram with customizable bins\n- `tg_calendar` - Calendar heatmap for time series data\n\n### Tables and Text\n- `rich_table` - Formatted table with colors (uses Rich library)\n- `figlet` - Large ASCII art text for KPIs (uses pyfiglet library)\n- `json` - Raw JSON output of query results (built-in)\n\n## SQL Query Format\n\nQueries must return specific column names depending on the chart type:\n\n### Standard Charts\n```sql\nSELECT \n  category as x,      -- X-axis values\n  SUM(amount) as y,   -- Y-axis values\n  status as color     -- Optional: color grouping\nFROM sales\nGROUP BY category, status\n```\n\n### Geographic Maps\n```sql\nSELECT \n  latitude as lat,    -- Latitude\n  longitude as lon,   -- Longitude\n  sales as value      -- Optional: heat value\nFROM store_locations\n```\n\n### Pie/Waffle Charts\n```sql\nSELECT \n  category as x,      -- Category labels\n  COUNT(*) as y       -- Values\nFROM products\nGROUP BY category\n```\n\n## Advanced Features\n\n### Live Refresh\nAdd an interval to auto-refresh charts:\n```bash\ncheshire \"SELECT ...\" bar 5s    # Refresh every 5 seconds\ncheshire \"SELECT ...\" line 1m    # Refresh every minute\ncheshire \"SELECT ...\" scatter 0.5h  # Refresh every 30 minutes\n```\n\n### Database Analysis\nAnalyze a database to generate chart suggestions:\n```bash\n# Analyze configured database\ncheshire --sniff --database sales\n\n# Analyze SQLite file\ncheshire --sniff --db mydata.db\n\n# Analyze CSV file\ncheshire --sniff --csv data.csv\n\n# Analyze Parquet folder\ncheshire --sniff --parquet /data/parquet/\n```\n\n### Chart Size Control\n```bash\n# Set explicit width and height in characters\ncheshire \"SELECT ...\" bar --width 60 --height 20\n\n# Use percentage of terminal size\ncheshire \"SELECT ...\" line --width \"80%\" --height \"50%\"\n\n# Mix absolute and percentage\ncheshire \"SELECT ...\" scatter --width \"75%\" --height 15\n\n# Small inline charts\ncheshire \"SELECT ...\" bar --width 40 --height 8\n```\n\n### Color Customization\n```bash\n# Named colors\ncheshire \"SELECT ...\" bar --color red\n\n# Hex colors\ncheshire \"SELECT ...\" line --color \"#FF5733\"\n\n# Themes\ncheshire \"SELECT ...\" scatter --theme matrix\n```\n\n### Script-Friendly Output\n```bash\n# Don't clear terminal before rendering (useful for scripts/logs)\ncheshire \"SELECT ...\" bar --no-clear\n\n# Capture output in scripts without terminal clearing\necho \"=== Sales Report ===\" >> report.log\ncheshire \"SELECT product as x, SUM(sales) as y FROM data GROUP BY 1\" bar --no-clear >> report.log\n\n# Build dashboards with multiple charts\ncheshire \"SELECT ...\" pie --no-clear\ncheshire \"SELECT ...\" bar --no-clear\ncheshire \"SELECT ...\" line --no-clear\n```\n\n## Interactive TUI Mode\n\nLaunch without arguments to enter the interactive TUI:\n\n```bash\ncheshire\n```\n\nFeatures:\n- Database browser with table listings\n- SQL query editor with syntax highlighting\n- Live preview of query results\n- Chart type selector with recommendations\n- Keyboard navigation and shortcuts\n\n### TUI Keyboard Shortcuts\n- `Tab` - Switch between panels\n- `Enter` - Execute query/select item\n- `Esc` - Exit/cancel\n- `Ctrl+Q` - Quit application\n- `Ctrl+C` - Copy current chart's CLI\n\n## Examples\n\n### Sales Dashboard\n```bash\n# Top products by revenue\ncheshire \"SELECT product as x, SUM(revenue) as y FROM sales GROUP BY product ORDER BY y DESC LIMIT 10\" bar --db sales.db\n\n# Sales trend over time\ncheshire \"SELECT DATE(order_date) as x, SUM(amount) as y FROM orders GROUP BY 1 ORDER BY 1\" line --db sales.db\n\n# Geographic distribution\ncheshire \"SELECT store_lat as lat, store_lon as lon, SUM(sales) as value FROM stores GROUP BY lat, lon\" map_heatmap --db sales.db\n```\n\n### System Monitoring\n```bash\n# Memory usage by process\ncheshire \"SELECT name as x, resident_size/1024/1024 as y FROM processes WHERE resident_size > 0 ORDER BY y DESC LIMIT 15\" bar --database osquery\n\n# Network connections\ncheshire \"SELECT remote_address as x, COUNT(*) as y FROM process_open_sockets GROUP BY remote_address ORDER BY y DESC LIMIT 10\" bar --database osquery\n\n# CPU time distribution\ncheshire \"SELECT name as x, (user_time + system_time) as y FROM processes ORDER BY y DESC LIMIT 20\" pie --database osquery\n```\n\n### Data Analysis\n```bash\n# Analyze CSV and view suggestions\ncheshire --sniff --csv sales_data.csv\n\n# Query Parquet files with complex aggregations\ncheshire \"WITH monthly AS (SELECT DATE_TRUNC('month', date) as month, SUM(sales) as total FROM data GROUP BY 1) SELECT month as x, total as y FROM monthly ORDER BY month\" line --parquet /data/\n\n# Join multiple data sources using DuckDB\ncheshire \"SELECT c.name as x, SUM(s.amount) as y FROM read_csv_auto('customers.csv') c JOIN sales s ON c.id = s.customer_id GROUP BY c.name\" bar --db sales.db\n\n# Export query results as JSON for further processing\ncheshire \"SELECT * FROM sales WHERE date >= '2024-01-01'\" json --db sales.db > sales_2024.json\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**No color output**: Force color mode with environment variable:\n```bash\nFORCE_COLOR=1 cheshire \"SELECT ...\" bar\n```\n\n**Database not found**: Check file path or configure in cheshire.yaml:\n```bash\ncheshire --list-databases  # Show configured databases\n```\n\n**osquery not detected**: Ensure osqueryi is installed and in PATH:\n```bash\nwhich osqueryi  # Should show path to osqueryi\n```\n\n**Chart too large/small**: Adjust terminal size or set explicit dimensions:\n```yaml\n# In cheshire.yaml\nchart_defaults:\n  width: 80\n  height: 24\n```\n\n![Alt text](https://raw.githubusercontent.com/ryrobes/cheshire/refs/heads/main/cheshire_snap0.jpg \"We're all mad here.\")\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## Acknowledgments\n\nBuilt with amazing open-source libraries including DuckDB, plotext, Rich, and many others.\n",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright (c) 2025 Ryan Robitaille\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy\n        of this software and associated documentation files (the \"Software\"), to deal\n        in the Software without restriction, including without limitation the rights\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n        copies of the Software, and to permit persons to whom the Software is\n        furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all\n        copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n        SOFTWARE.\n        ",
    "summary": "Terminal-based SQL visualization tool that transforms query results into beautiful ANSI charts",
    "version": "0.1.1",
    "project_urls": {
        "Bug Reports": "https://github.com/ryrobes/cheshire/issues",
        "Documentation": "https://github.com/ryrobes/cheshire#readme",
        "Homepage": "https://github.com/ryrobes/cheshire",
        "Repository": "https://github.com/ryrobes/cheshire"
    },
    "split_keywords": [
        "sql",
        " visualization",
        " terminal",
        " charts",
        " database",
        " duckdb",
        " cli"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d6dd630fbba703c9a4d962d7ca81a71f614bf00374fc89dc99ec7ac1bb5401e8",
                "md5": "2e0ea68b9769c136ce2e7f88c2d179ee",
                "sha256": "bdfb1daa4933e6a66f1786d9b570047ba7a2391a381712a215d23b34e860f000"
            },
            "downloads": -1,
            "filename": "cheshire_sql-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2e0ea68b9769c136ce2e7f88c2d179ee",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 105931,
            "upload_time": "2025-08-09T00:00:56",
            "upload_time_iso_8601": "2025-08-09T00:00:56.597269Z",
            "url": "https://files.pythonhosted.org/packages/d6/dd/630fbba703c9a4d962d7ca81a71f614bf00374fc89dc99ec7ac1bb5401e8/cheshire_sql-0.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "447f96beafcd336618cb5aa1eb2f3583c50e36a9df8dcbd16dabf3a7b03d673e",
                "md5": "73adaee7156bfda5762257cb6d36df47",
                "sha256": "6711dd6125c2231ac12e8cb9b76e3958e65b13fae84dec5342b83befa0491551"
            },
            "downloads": -1,
            "filename": "cheshire_sql-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "73adaee7156bfda5762257cb6d36df47",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 116331,
            "upload_time": "2025-08-09T00:00:57",
            "upload_time_iso_8601": "2025-08-09T00:00:57.700790Z",
            "url": "https://files.pythonhosted.org/packages/44/7f/96beafcd336618cb5aa1eb2f3583c50e36a9df8dcbd16dabf3a7b03d673e/cheshire_sql-0.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-09 00:00:57",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "yourusername",
    "github_project": "cheshire",
    "github_not_found": true,
    "lcname": "cheshire-sql"
}