Agent Skills › zebbern/claude-code-guide › database-scout

database-scout

GitHub

提供SQLite和PostgreSQL数据库的只读探索功能，支持列出表、检查模式、预览数据、生成ER图及执行安全查询。具备严格的SQL白名单和注入防护机制。

skills/database-scout/SKILL.md zebbern/claude-code-guide

Trigger Scenarios

探索数据库结构查看表定义或列信息生成ER图执行只读SQL查询预览表格数据

Install

npx skills add zebbern/claude-code-guide --skill database-scout -g -y

More Options

Use without installing

npx skills use zebbern/claude-code-guide@database-scout

指定 Agent (Claude Code)

npx skills add zebbern/claude-code-guide --skill database-scout -a claude-code -g -y

安装 repo 全部 skill

npx skills add zebbern/claude-code-guide --all -g -y

预览 repo 内 skill

npx skills add zebbern/claude-code-guide --list

SKILL.md

Frontmatter

{
    "name": "database-scout",
    "license": "MIT",
    "description": "Explore SQLite and PostgreSQL databases: list tables, inspect schemas (columns\/types\/constraints), preview data, generate Mermaid ER diagrams, and run safe read-only queries. Triggered by requests to explore a database, view table structures, describe tables, generate diagrams, or query data, and by keywords like database exploration, schema, ER diagram, or SQL query."
}

database-scout

Read-only exploration tool for SQLite / PostgreSQL databases — inspect table schemas, preview data, generate ER diagrams, and run safe queries.

Feature Overview

Feature	Description
List all tables	Show tables and views in the database, with row counts
Inspect table schema	Column names, types, constraints (PK/FK/NOT NULL), indexes, defaults
Data preview	View the first N rows of a table
ER diagram generation	Output Mermaid erDiagram syntax, ready to render
Safe read-only queries	Only SELECT/WITH/EXPLAIN allowed; write operations are blocked

Security Mechanisms

Connection-level read-only: SQLite opens with ?mode=ro URI; PostgreSQL uses SET SESSION READ ONLY
SQL whitelist: Only statements starting with SELECT / WITH / EXPLAIN / PRAGMA / SHOW are allowed
Dangerous keyword blocking: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, and 30+ other keywords are blocked
Multi-statement blocking: Semicolon-separated multiple SQL statements are rejected (prevents injection)
Identifier escaping: Table names are double-quote escaped to prevent SQL injection

Quick Start

# List all tables in a SQLite database
python3 scripts/db_explorer.py --db-path data.db list-tables

# Inspect table schema
python3 scripts/db_explorer.py --db-path data.db describe users

# Preview data (default 20 rows)
python3 scripts/db_explorer.py --db-path data.db preview orders --limit 10

# Generate Mermaid ER diagram
python3 scripts/db_explorer.py --db-path data.db er-diagram

# Run a read-only query
python3 scripts/db_explorer.py --db-path data.db query "SELECT name, age FROM users WHERE age > 18 LIMIT 10"

PostgreSQL

# Connect to PostgreSQL
python3 scripts/db_explorer.py --db-type postgres --dsn "host=localhost dbname=mydb user=reader" list-tables

# Inspect table schema
python3 scripts/db_explorer.py --db-type postgres --dsn "host=localhost dbname=mydb user=reader" describe orders

Detailed Usage

Parameters

Parameter	Required	Default	Description
`--db-type`	No	sqlite	Database type: sqlite or postgres
`--db-path`	Yes (for SQLite)	—	Path to the SQLite database file
`--dsn`	Yes (for PostgreSQL)	—	PostgreSQL connection string

Subcommands

Command	Description	Example
`list-tables`	List all tables/views	`list-tables`
`describe <table>`	Show detailed table schema	`describe users`
`preview <table> [--limit N / -n N]`	Preview the first N rows	`preview orders --limit 5`
`er-diagram`	Generate Mermaid ER diagram	`er-diagram`
`query "<sql>"`	Run a read-only SQL query	`query "SELECT count(*) FROM users"`

Output Examples

list-tables

[
  {"name": "users", "type": "table", "row_count": 1500},
  {"name": "orders", "type": "table", "row_count": 8200},
  {"name": "user_stats", "type": "view", "row_count": 1500}
]

describe

{
  "table": "orders",
  "row_count": 8200,
  "columns": [
    {"cid": 0, "name": "id", "type": "INTEGER", "notnull": true, "default": null, "primary_key": true},
    {"cid": 1, "name": "user_id", "type": "INTEGER", "notnull": true, "default": null, "primary_key": false},
    {"cid": 2, "name": "amount", "type": "REAL", "notnull": false, "default": "0.0", "primary_key": false}
  ],
  "foreign_keys": [
    {"from": "user_id", "to_table": "users", "to_column": "id"}
  ],
  "indexes": [
    {"name": "idx_orders_user_id", "unique": false, "columns": ["user_id"]}
  ]
}

er-diagram (Mermaid)

erDiagram
    users {
        INTEGER id PK
        TEXT name
        TEXT email
        INTEGER age
    }
    orders {
        INTEGER id PK
        INTEGER user_id FK
        REAL amount
        TEXT created_at
    }
    users ||--o{ orders : "user_id"