runsql

A hybrid CLI & Web tool to run SQL queries on CSV, XLSX, and JSON files, written in Go.

🎯 Features

• CLI Mode: Execute SQL queries from the terminal with Unix philosophy
• Web Mode: Spin up a localhost server with a GUI for non-technical users
• Multi-Format Support: Parse and query CSV, XLSX, and JSON files
• In-Memory SQLite: Load files into SQLite for fast querying
• Type Inference: Automatically detect column types (INTEGER, REAL, TEXT)
• Multiple Output Formats: Table, JSON, or CSV output
• Hexagonal Architecture: Clean separation of concerns (Ports & Adapters)

📋 Requirements

• Go 1.21+
• SQLite3 (with CGO enabled for go-sqlite3)
• Windows/Linux/macOS (cross-platform support)

🚀 Installation

From Source

# Clone or download the repository
git clone https://github.com/zulfikawr/runsql
cd runsql

# Install dependencies
go mod download

# Build the executable
go build -o runsql ./cmd/runsql
# or
go build -o runsql.exe ./cmd/runsql # for Windows

Pre-built Binary

Download the compiled executable from the Releases page.

📖 Usage

CLI Mode (Default)

Execute SQL queries directly from the terminal.

Basic Syntax

./runsql -f <file> -q <query> -o <format>

Parameters

Examples

Example 1: Query CSV with table output

./runsql -f sample/sample.csv -q "SELECT industry, COUNT(*) as count FROM sample WHERE level = 0 GROUP BY industry" -o table

Output:

| industry | count |
+----------+-------+
| total    | 705     |

Example 2: Query JSON with JSON output

./runsql -f sample/sample.json -q "SELECT language, COUNT(*) as users FROM sample GROUP BY language ORDER BY users DESC" -o json

Output:

[
  {
    "language": "Sindhi",
    "users": 1000
  }
]

Example 3: Query with CSV output

./runsql -f data.csv -q "SELECT name, email FROM data WHERE age > 30" -o csv

Output:

name,email
John Doe,[email protected]
Jane Smith,[email protected]

Example 4: JOIN Query (Multi-File)

./runsql -f users.csv,orders.json -q "SELECT users.name, orders.item FROM users JOIN orders ON users.id = orders.user_id"

Web Mode

Launch an interactive web interface for querying files.

Syntax

./runsql -web -addr ":8080"

Parameters

Example

./runsql -web -addr ":3000"

Then open your browser to http://localhost:3000 and:

1. Upload a CSV, XLSX, or JSON file
2. Enter an SQL query
3. View results in the browser

📂 Project Structure

runsql/
├── cmd/
│   └── runsql/              # Entry point
│       └── main.go          # CLI/Web mode dispatcher
├── internal/
│   ├── adapter/             # Interface adapters (Ports & Adapters pattern)
│   │   ├── cli/             # CLI-specific logic
│   │   │   └── cli.go
│   │   └── web/             # HTTP handlers & server
│   │       └── web.go
│   ├── core/                # Business logic (The Brain)
│   │   ├── domain.go        # Struct definitions
│   │   ├── engine.go        # SQLite lifecycle & query execution
│   │   ├── engine_test.go   # Unit tests
│   │   └── infer.go         # Type inference logic
│   ├── parsers/             # File readers (Ports)
│   │   ├── parser.go        # Interface definition
│   │   ├── csv.go           # CSV parser
│   │   ├── json.go          # JSON parser
│   │   ├── xlsx.go          # Excel parser
│   │   └── parsers_test.go  # Unit tests
│   └── ui/                  # UI logic
│       ├── colors.go        # Colors definition
├── web/                     # Static frontend assets
│   ├── index.html           # Web UI
│   ├── script.js            # JavaScript
│   └── style.css            # Styling
├── go.mod                   # Go module definition
├── go.sum                   # Go module lock file
├── LICENSE                  # MIT License
├── .gitignore              # Git ignore rules
└── README.md               # This file

🏗️ Architecture

RunSQL follows the Hexagonal Architecture (Ports & Adapters) pattern:

┌────────────────────────────────────┐
│         User Interfaces            │
│  (CLI Adapter)  │   (Web Adapter)  │
└──────