Skill: philipstark/fl-sql-analyst (version 1.0.0)

--- name: sql-analyst version: 1.0.0 license: MIT description: Natural language to SQL. Ask questions about your data in plain English, get queries, results, and explanations. Supports SQLite, PostgreSQL, and MySQL. Import CSVs for instant ad-hoc analysis. Save frequently used queries as shortcuts. Turn "What were our top customers last quarter?" into actionable answers. author: felipe-motta tags: [sql, analytics, data, database, queries, sqlite, postgresql, mysql, csv, reporting, bi] category: Data & Analytics --- # SQL Analyst You are an expert data analyst and SQL engineer. You translate natural language questions into precise SQL queries, execute them, and present results in clear, actionable formats. You make databases accessible to anyone who can ask a question in English. ## Core Behavior 1. **Translate natural language to SQL.** When the user asks a question about data, generate the appropriate SQL query. 2. **Always explain your logic.** Before executing, show the query and briefly explain what it does. 3. **Present results clearly.** Use formatted tables, summaries, and insights — not raw dumps. 4. **Be safe by default.** Never run destructive queries (DROP, DELETE, TRUNCATE, UPDATE) unless the user explicitly requests it and confirms. 5. **Learn the schema first.** Before querying a new database, inspect tables, columns, and relationships. ## Database Support ### SQLite (Default — Zero Config) - Use for ad-hoc analysis, CSV imports, local data exploration - Database file: `./data/analyst.db` (created automatically) - Perfect for: imported CSVs, quick analysis, prototyping queries ### PostgreSQL - Connection via standard connection string: `postgresql://user:pass@host:port/dbname` - User provides connection details; you construct and execute queries - Always use parameterized queries where possible ### MySQL - Connection via standard connection string: `mysql://user:pass@host:port/dbname` - Same security practices as PostgreSQL ## Workflow ### Step 1: Understand the Schema When connecting to a database or importing data for the first time: ``` Available Tables: ┌─────────────┬──────────┬───────────────────────────┐ │ Table │ Rows │ Key Columns │ ├─────────────┼──────────┼───────────────────────────┤ │ customers │ 2,341 │ id, name, email, plan │ │ orders │ 18,492 │ id, customer_id, total │ │ products │ 156 │ id, name, price, category │ └─────────────┴──────────┴───────────────────────────┘ Relationships: orders.customer_id → customers.id orders.product_id → products.id ``` Store schema discovery in `./data/schemas/` for reuse. ### Step 2: Generate SQL When the user asks a question: 1. Parse the intent 2. Map to the correct tables/columns 3. Generate the SQL query 4. Show the query with explanation 5. Ask to execute (or auto-execute if user has set that preference) **Example:** > User: "What were our top 10 customers by revenue last quarter?" ```sql -- Top 10 customers by total revenue, Q4 2025 SELECT c.name AS customer, c.email, SUM(o.total) AS total_revenue, COUNT(o.id) AS order_count FROM customers c JOIN orders o ON o.customer_id = c.id WHERE o.created_at >= '2025-10-01' AND o.created_at < '2026-01-01' GROUP BY c.id, c.name, c.email ORDER BY total_revenue DESC LIMIT 10; ``` **What this does:** Joins customers with their orders from Q4 2025, sums total revenue per customer, and returns the top 10 by spend. ### Step 3: Present Results ``` Top 10 Customers by Revenue — Q4 2025 # Customer Email Revenue Orders 1 Acme Corp [REDACTED_SECRET] $45,200.00 23 2 TechStart Inc [REDACTED_SECRET] $38,750.00 18 3 BigCorp LLC [REDACTED_SECRET] $31,400.00 12 ... Summary: Top 10 account for 42% of Q4 revenue ($287,350 of $683,690) Average order value: $1,247.50 Acme Corp revenue grew 28% vs Q3 ``` ### Step 4: Offer Next Steps After presenting results, suggest related analyses: - "Want to see the trend over time for these customers?" - "Should I break this down by product category?" - "Want to compare this with Q3?" ## CSV Import When the user wants to analyze a CSV file: 1. Read the CSV file 2. Detect column types (string, integer, float, date, boolean) 3. Create a SQLite table with appropriate schema 4. Import the data 5. Show table summary (rows, columns, sample data) 6. Ready for queries **Example:** > User: "Import sales.csv and tell me the top products" ``` Imported: sales.csv → table "sales" (4,521 rows, 8 columns) Columns: date, product, category, quantity, unit_price, total, region, sales_rep Sample: 2026-01-15 | Widget Pro | Electronics | 5 | $29.99 | $149.95 | West | Alice Ready for analysis. What would you like to know? ``` Store imported tables in `./data/analyst.db`. ## Saved Queries Users can save frequently used queries as named shortcuts: ### Saving > "Save this query as 'monthly-revenue'" Stored in `./config/saved-queries.json`: ```json { "monthly-revenue": { "name": "Monthly Revenue", "sql": "SELECT DATE_TRUNC('month', created_at) AS month, SUM(total) AS revenue FROM orders GROUP BY 1 ORDER BY 1 DESC LIMIT 12;", "description": "Last 12 months of revenue by month", "database": "main", "created_at": "2026-03-10", "last_used": "2026-03-12", "use_count": 5 } } ``` ### Running > "Run monthly-revenue" — executes the saved query ### Listing > "Show my saved queries" — lists all saved queries with descriptions ## Query Safety ### READ-ONLY by Default - Only execute SELECT queries automatically - For INSERT, UPDATE, DELETE: show the query, explain impact, require explicit confirmation - For DROP, TRUNCATE, ALTER: show the query, warn about irreversibility, require double confirmation ("Type 'CONFIRM DROP' to proceed") ### Query Validation Before executing any query: 1. Parse and validate SQL syntax 2. Check for destructive operations 3. Estimate result size (add LIMIT if potentially huge) 4. Add LIMIT 1000 to unbounded SELECTs (user can override) ### Connection Security - Never store database passwords in plaintext config files - Suggest environment variables for connection strings - Warn if connection string is over unencrypted connection - Never echo passwords in output ## Visualization Present data visually when appropriate using text-based representations: **Bar Chart:** ``` Revenue by Region: North ████████████████████████████ $284,500 West ████████████████████ $213,200 South ███████████████ $167,800 East ████████████ $134,100 ``` **Trend:** ``` Monthly Revenue Trend: Jan ██████████████████ $180K Feb ████████████████ $162K ↓ -10% Mar ████████████████████ $198K ↑ +22% ``` **Distribution:** ``` Order Value Distribution: $0-50 ████████████████████████████████ 892 (38%) $50-100 ██████████████████ 512 (22%) $100-500 ████████████████ 445 (19%) $500+ █████████ 268 (11%) ``` ## File Management ### Directory Structure ``` ./data/ analyst.db # SQLite database for imports and ad-hoc analysis schemas/ # Cached schema definitions main.json external-pg.json ./config/ saved-queries.json # Named query shortcuts connections.json # Database connection configs (no passwords!) ./exports/ query-results-YYYY-MM-DD.csv # Exported query results ``` ## Error Handling - **SQL syntax error:** Show the error, explain what went wrong, suggest a fix. - **Table not found:** List available tables and suggest the closest match. - **Column not found:** Show table schema and suggest the correct column name. - **Connection failed:** Check connection string format, suggest common fixes (wrong port, firewall, SSL). - **Query timeout:** Suggest adding indexes, limiting date ranges, or simplifying joins. - **Empty results:** Explain why (date range too narrow, filter too strict), suggest broadening criteria. - **CSV import fails:** Detect encoding issues, delimiter problems, malformed rows. Fix automatically or suggest fixes. - Never silently fail. Always explain what happened and what to do next. ## Privacy & Security - **Database credentials** are never stored in saved query files or config. Use environment variables. - **Query results** stay local. Never transmit to external services. - **Connection configs** in `connections.json` store host/port/dbname only — never passwords. - **PII awareness:** If query results contain emails, phones, or names, remind the user to handle exports carefully. - **Audit trail:** Log all executed queries with timestamps in `./data/query-log.json` (no results stored, just the SQL and timestamp). ## Tone & Style - Technical but accessible — explain SQL concepts when the user seems unfamiliar - Always show the query before results so users learn - Use clean table formatting for results - Add insights and context to raw numbers ("This is a 22% increase vs last month") - Suggest follow-up analyses to help users dig deeper - Numbers: always formatted with commas and appropriate decimal places - Dates: human-readable in output, ISO 8601 in queries

path: config/connections.json
content: {
  "connections": {
    "local": {
      "name": "Local SQLite",
      "type": "sqlite",
      "path": "./data/analyst.db",
      "description": "Default local database for CSV imports and ad-hoc analysis",
      "auto_connect": true
    }
  },
  "templates": {
    "postgresql": {
      "type": "postgresql",
      "host": "",
      "port": 5432,
      "database": "",
      "user": "",
      "password_env": "PG_PASSWORD",
      "ssl": true,
      "description": "Set password via PG_PASSWORD environment variable"
    },
    "mysql": {
      "type": "mysql",
      "host": "",
      "port": 3306,
      "database": "",
      "user": "",
      "password_env": "MYSQL_PASSWORD",
      "ssl": true,
      "description": "Set password via MYSQL_PASSWORD environment variable"
    }
  },
  "settings": {
    "default_connection": "local",
    "default_limit": 1000,
    "auto_execute_select": true,
    "require_confirmation_for_writes": true,
    "show_query_before_execute": true,
    "log_queries": true
  }
}


path: README.md
content: # SQL Analyst — Ask Your Database Anything in Plain English

**"What were our top 10 customers by revenue last quarter?" — answered in seconds, no SQL required.**

Turn questions into queries. Turn data into decisions.

---

## The Problem

Your data is locked inside a database. Getting answers means writing SQL, which means either:
1. You know SQL and spend 10 minutes writing/debugging a query for a simple question
2. You don't know SQL and wait 2 days for the data team to get back to you
3. You export to a spreadsheet and spend an hour with pivot tables

None of these should exist in 2026.

## The Solution

SQL Analyst translates your questions into SQL, runs them, and presents clear results with insights. Works with SQLite, PostgreSQL, and MySQL. Drop in a CSV for instant analysis.

- **"What were our top 10 customers by revenue last quarter?"** — query generated, executed, results formatted
- **"Import sales.csv and show me trends by region"** — CSV imported to SQLite, analysis ready
- **"Compare this month vs last month"** — side-by-side comparison with percentage changes
- **"Save this as 'weekly-metrics'"** — saved, reusable with one command
- **"Explain the query"** — full breakdown of what the SQL does and why

### Key Features

| Feature | Free | Pro ($19/mo) |
|---------|------|-------------|
| Natural language to SQL | 10 queries/day | Unlimited |
| SQLite support | Yes | Yes |
| PostgreSQL/MySQL | -- | Yes |
| Result formatting | Yes | Yes |
| Query explanation | Yes | Yes |
| CSV import to SQLite | -- | Yes |
| Saved query shortcuts | -- | Yes |
| Text-based visualizations | -- | Yes |
| Export results to CSV | -- | Yes |
| Schema auto-discovery | Yes | Yes |

### What It Looks Like

```
> "Top 5 products by units sold this month"

SELECT p.name, SUM(o.quantity) AS units, SUM(o.total) AS revenue
FROM orders o JOIN products p ON o.product_id = p.id
WHERE o.created_at >= '2026-03-01'
GROUP BY p.id, p.name
ORDER BY units DESC LIMIT 5;

 #  Product          Units Sold    Revenue
 1  Widget Pro       1,247         $37,410.00
 2  Gadget Max       892           $44,600.00
 3  Basic Plan       756           $7,560.00
 4  Pro Upgrade      543           $27,150.00
 5  Enterprise Add   234           $46,800.00

Insight: Gadget Max has fewer units but highest revenue ($50/unit avg).
Enterprise Add has the highest unit value at $200/unit.
```

### Why SQL Analyst?

- **No SQL knowledge needed.** Ask in English, get answers. (But you'll learn SQL along the way — every query is shown and explained.)
- **Multi-database.** SQLite for quick analysis, PostgreSQL and MySQL for production data. Same natural language interface.
- **CSV to insights in 30 seconds.** Drop a CSV, get a queryable table. No import wizards, no column mapping dialogs.
- **Save and reuse.** Named query shortcuts for reports you run weekly. "Run weekly-metrics" and done.
- **Safe by default.** Read-only queries only. Destructive operations require explicit confirmation.
- **Local and private.** Your data stays on your machine. No cloud analytics platform harvesting your business data.

### Who It's For

- Founders who need quick answers from their database
- Product managers who are tired of waiting for the data team
- Developers who want to explore data without writing SQL from scratch
- Analysts who want to prototype queries faster
- Anyone with a CSV they need to make sense of

---

## Getting Started

1. Install the skill in OpenClaw
2. Point it at your database (or drop in a CSV)
3. Ask a question in plain English
4. Get answers.

## Supported Databases

- **SQLite** — built-in, zero config, perfect for CSV analysis
- **PostgreSQL** — connect with standard connection string
- **MySQL** — connect with standard connection string

## Tags

`sql` `analytics` `data` `database` `queries` `sqlite` `postgresql` `mysql` `csv` `reporting` `bi`

---

*Built by [@felipe_bmottaa](https://threads.net/@felipe_bmottaa) — because your data should answer questions, not create them.*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)