db-explorer

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 注入

Quick Start

# 列出 SQLite 数据库中的所有表
python3 scripts/db_explorer.py --db-path data.db list-tables

# 查看表结构
python3 scripts/db_explorer.py --db-path data.db describe users

# 预览数据（默认 20 行）
python3 scripts/db_explorer.py --db-path data.db preview orders --limit 10

# 生成 Mermaid ER 图
python3 scripts/db_explorer.py --db-path data.db er-diagram

# 执行只读查询
python3 scripts/db_explorer.py --db-path data.db query "SELECT name, age FROM users WHERE age > 18 LIMIT 10"

PostgreSQL

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

# 查看表结构
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