database-scout

database-scout

用于只读探索 SQLite / PostgreSQL 数据库的工具——检查表结构、预览数据、生成 ER 图并运行安全查询。

功能概览

功能	描述
列出所有表	显示数据库中的表和视图，并显示行数
检查表结构	列名、类型、约束（PK/FK/NOT NULL）、索引、默认值
数据预览	查看表中的前 N 行
生成 ER 图	输出 Mermaid erDiagram 语法，可直接渲染
安全只读查询	仅允许 SELECT/WITH/EXPLAIN；禁止写入操作

安全机制

• 连接级只读：SQLite 使用 ?mode=ro URI 打开；PostgreSQL 使用 SET SESSION READ ONLY
• SQL 白名单：仅允许以 SELECT / WITH / EXPLAIN / PRAGMA / SHOW 开头的语句
• 拦截危险关键字：INSERT、UPDATE、DELETE、DROP、ALTER、CREATE 及其他 30 多个关键字均会被拦截
• 拦截多语句：拒绝以分号分隔的多条 SQL 语句（防止注入）
• 标识符转义：表名使用双引号转义，以防止 SQL 注入

快速开始

# 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

详细用法

参数

参数	必填	默认值	描述
--db-type	否	sqlite	数据库类型：sqlite 或 postgres
--db-path	是（用于 SQLite）	—	SQLite 数据库文件的路径
--dsn	是（用于 PostgreSQL）	—	PostgreSQL 连接字符串

子命令

命令	描述	示例
list-tables	列出所有表/视图	list-tables
describe <table>	显示详细的表结构	describe users
preview <table> [--limit N / -n N]	预览前 N 行	preview orders --limit 5
er-diagram	生成 Mermaid ER 图	er-diagram
query "<sql>"	运行只读 SQL 查询	query "SELECT count(*) FROM users"

输出示例

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"

依赖项

• Python 3.8+（sqlite3 是内置模块）
• PostgreSQL 支持需要：pip install psycopg2-binary