# sql2doc

**Repository Path**: LittleY98/sql2doc

## Basic Information

- **Project Name**: sql2doc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-03
- **Last Updated**: 2025-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据库表结构说明文档生成工具

一个命令行工具，能够从标准的数据库建表 SQL 文件中自动提取表结构信息，并生成格式规范的 Word 文档（`.docx`）。

## 功能特性

- ✅ 支持解析包含多个 `CREATE TABLE` 语句的 SQL 文件
- ✅ 支持 MySQL、PostgreSQL、人大金仓（KingbaseES）三种数据库
- ✅ 自动提取字段信息：字段名、类型、长度、是否允许空、默认值、备注
- ✅ 生成格式规范的 Word 文档，包含封面和表格
- ✅ 支持中文字段名和注释
- ✅ 命令行接口，使用简单

## 安装

### 使用 uv（推荐）

```bash
# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv sync

# 安装到系统（可选）
uv pip install -e .
```

### 使用 pip

```bash
pip install sqlglot python-docx
```

## 使用方法

### 基本用法

```bash
# 使用 python -m 方式运行
python -m sql2doc -i example.sql -o output.docx -d mysql

# 如果已安装为命令，可直接使用
sql2doc -i example.sql -o output.docx -d mysql
```

### 参数说明

| 参数 | 短参数 | 是否必填 | 说明 |
|------|--------|----------|------|
| `--input` | `-i` | ✅ 是 | 输入的 SQL 脚本文件路径 |
| `--output` | `-o` | ❌ 否 | 输出的 `.docx` 文件路径（默认：`schema_document.docx`） |
| `--dialect` | `-d` | ❌ 否 | 数据库类型：`mysql`（默认）、`postgres`、`kingbase` |

### 示例

```bash
# MySQL 数据库
python -m sql2doc -i schema.sql -o mysql_doc.docx -d mysql

# PostgreSQL 数据库
python -m sql2doc -i schema.sql -o postgres_doc.docx -d postgres

# 人大金仓数据库
python -m sql2doc -i schema.sql -o kingbase_doc.docx -d kingbase

# 使用默认输出文件名
python -m sql2doc -i schema.sql -d mysql
```

## 输入文件格式

输入文件应为 UTF-8 编码的 SQL 文件，包含标准的 `CREATE TABLE` 语句：

```sql
CREATE TABLE product (
    id BIGINT PRIMARY KEY COMMENT '商品ID',
    name VARCHAR(200) NOT NULL COMMENT '商品名称',
    price DECIMAL(10,2) DEFAULT 0.00 COMMENT '价格',
    status TINYINT NOT NULL DEFAULT 1 COMMENT '状态：1-上架，0-下架',
    detail TEXT COMMENT '详情描述',
    create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) COMMENT='商品表';
```

## 输出文档格式

生成的 Word 文档包含：

1. **封面页**
   - 文档标题："数据库表结构说明文档"
   - 生成时间
   - 数据库类型标识

2. **正文部分**
   - 每张表单独一节
   - 表名作为一级标题
   - 字段说明表格，包含以下列：
     - 字段名
     - 类型
     - 长度
     - 允许空
     - 默认值
     - 备注

## 项目结构

```
sql2doc/
├── sql2doc/
│   ├── __init__.py
│   ├── __main__.py      # 模块入口
│   ├── models.py         # 数据模型
│   ├── parser.py         # SQL解析模块
│   ├── writer.py         # Word文档生成模块
│   └── cli.py            # 命令行接口
├── example.sql           # 示例SQL文件
├── pyproject.toml        # 项目配置和依赖
└── README.md             # 本文件
```

## 开发

### 项目依赖

- Python 3.8+
- sqlglot >= 23.0.0
- python-docx >= 1.1.0

### 运行测试

```bash
# 使用示例文件测试
python -m sql2doc -i example.sql -o test_output.docx -d mysql
```

## 限制说明

- 仅支持 `CREATE TABLE` 语句
- 不支持视图、索引、触发器
- 不支持存储过程和函数
- 不支持跨文件引用分析

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！