Sql Reader

SQL Reader Skill

Read table structures and query data from PostgreSQL, SQL Server, Oracle, and SQLite. All queries are strictly read-only (SELECT only), enforced by the Python script with multi-layer security.

Prerequisites

Environment Setup

Before any database operation, ensure the Python virtual environment is ready. Run this ONCE per session (or when dependencies are missing):

py scripts/setup_env.py

This script:

1. Checks Python >= 3.8 (uses py launcher on Windows)
2. Creates .venv/ in the skill folder (where SKILL.md is located)
3. Installs database drivers into the venv

If Python is not found or version --db-type [PARAMS]

Linux/macOS

.venv/bin/python scripts/db_query.py --mode --db-type [PARAMS]

### test_conn — Test Database Connection

```bash
.venv/Scripts/python.exe scripts/db_query.py --mode test_conn --db-type pgsql --host localhost --port 5432 --user myuser --password mypass --database mydb

Use this to verify connectivity before running other operations.

list_tables — List All Tables

.venv/Scripts/python.exe scripts/db_query.py --mode list_tables --db-type pgsql --host localhost --port 5432 --user myuser --password mypass --database mydb

Returns: {"success": true, "data": [{"table_name": "...", "table_type": "BASE TABLE|VIEW"}], "row_count": N}

describe — Show Table Structure

.venv/Scripts/python.exe scripts/db_query.py --mode describe --db-type pgsql --host localhost --port 5432 --user myuser --password mypass --database mydb --table users

Returns column details: name, data type, max length, precision, nullable, default value, primary key.

query — Execute SELECT Query

.venv/Scripts/python.exe scripts/db_query.py --mode query --db-type pgsql --host localhost --port 5432 --user myuser --password mypass --database mydb --sql "SELECT * FROM users WHERE age > 18"

Returns: {"success": true, "data": [...], "columns": [...], "row_count": N}

Natural Language Query Workflow

When the user describes a query need in natural language (not raw SQL), follow this workflow:

Step 1: Ensure Environment

Run py scripts/setup_env.py if not done yet. Capture the venv Python path from the output.

Step 2: Collect Connection Info

Check if the user already provided connection details. If not, ask:

• Which database type? (pgsql / sqlserver / oracle / sqlite)
• Required parameters for that type (see table above)

Step 3: List Tables

Run list_tables to discover available tables. This helps you understand the schema.

If the user's request is vague ("show me the data"), present the table list and ask what they want to see.

Step 4: Describe Relevant Tables

Based on the user's intent, run describe on 1-3 tables most likely relevant. You can batch these calls.

If unsure which tables are relevant, describe tables whose names match keywords from the user's request.

Step 5: Generate SQL

Using the table structure information, generate a SELECT query:

• Respect SQL dialect differences per database type
• Use correct column names and types from the describe output
• For time-relative conditions ("last month", "this week"), use appropriate database date functions
• The script will auto-append LIMIT/TOP if not present (default 200 rows)
• Only generate SELECT statements — any other statement type will be rejected by the script

SQL Dialect Notes:

• PostgreSQL: LIMIT N, NOW(), EXTRACT(), ILIKE
• SQL Server: TOP N, GETDATE(), DATEPART(), NOLOCK
• Oracle: FETCH FIRST N ROWS ONLY, SYSDATE, TRUNC(), ROWNUM
• SQLite: LIMIT N, datetime('now'), strftime()

Step 6: Execute and Present

Run the generated query via query mode. Present results to the user in a readable format.

For complex queries (JOINs, subqueries, aggregations), show the generated SQL to the user first and briefly explain the logic before executing.

Security

Read-only access is enforced at THREE levels in the Python script:

1. Regex whitelist: SQL must start with SELECT
2. Keyword blacklist: Scans for INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, EXEC, etc.
3. Connection-level readonly: Each database connection is set to read-only mode

The script will return {"success": false, "error": "BLOCKED: ..."} if any write operation is attempted.

Error Handling

All errors are returned as JSON: {"success": false, "error": "..."}

Common errors:

• Connection refused: Wrong host/port or database not running
• Authentication failed: Wrong user/password
• Database not found: Wrong database name
• Table not found: Table name case sensitivity (Oracle stores uppercase)
• BLOCKED: Write operation attempted
• Query timed out: Query exceeds 30-second limit

When an error occurs, explain it to the user and suggest fixes.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yansijian
• Source: yansijian/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.