# upgrade_sql

**Repository Path**: MM-Q/upgrade_sql

## Basic Information

- **Project Name**: upgrade_sql
- **Description**: ctc自动升级工具sql执行模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PostgreSQL SQL 执行工具

一个基于Go语言开发的SQL执行工具，专门用于批量执行PostgreSQL数据库的SQL脚本。支持分层执行、版本控制、增量执行、执行记录跟踪等功能，适用于数据库升级、迁移和初始化场景。

## 功能特性

### 核心功能
- **分层执行架构**：按照schema→business→validation的顺序分层执行SQL文件
- **版本控制与增量执行**：通过version.txt文件控制当前执行版本，支持跳过已执行文件
- **断点续执行**：支持从中断点继续执行，提高容错性
- **执行记录跟踪**：详细记录每个SQL文件的执行状态和时间戳
- **多环境支持**：支持主机直连和Docker容器两种执行环境
- **灵活的目录管理**：支持根据SQL_TYPE变量选择省级(sheng)或市级(shi)SQL目录
- **配置驱动设计**：通过TOML配置文件控制所有行为
- **完善的日志系统**：分级日志记录，支持INFO、ERROR等不同级别
- **错误处理与容错**：连接超时控制、执行失败处理、错误恢复机制

### 高级特性
- **模式切换**：通过ENABLE_SQL_TYPE_MODE控制是否启用SQL_TYPE模式
- **占位符替换**：支持动态替换配置文件中的变量占位符
- **自动数据库检查**：执行前自动检查目标数据库是否存在
- **连接测试**：执行前验证数据库连接可用性
- **跨平台支持**：提供Linux（.sh）和Windows（.bat）两种执行脚本

## 快速开始

### 1. 配置文件

编辑 `config.toml` 文件，配置数据库连接和执行参数：

```toml
# 数据库配置
[database]
host = 'data_base_host'
port = data_base_port
user = 'data_base_user'
password = 'data_base_passwd'
exec_env = 'DB_EXEC_ENV'
docker_container = 'DB_DOCKER_CONTAINER'
psql_path = 'data_base_psql_dir'

# 执行配置
[execution]
dry_run = false
skip_confirm = true
db_only = ''
connect_timeout = 5

# 目录配置
[directory]
sql_dir = 'sql_dir_path'  # 占位符，将被脚本替换
file_pattern = '*.sql'

# 版本控制配置
[version]
enabled = true
skip_executed = true

# 日志配置
[logging]
dir = 'temp_log_path'
file = 'temp_log_name'
print_config = true
```

### 2. SQL目录结构

支持两种SQL目录组织方式：

#### 标准模式（默认）
```
sql/
├── 01_schema/           # 数据库模式定义
│   └── postgres/        # PostgreSQL特定脚本
├── 02_business/         # 业务逻辑脚本
│   └── test_db/         # 测试数据库脚本
└── 03_validation/       # 验证脚本
    └── test_db/         # 测试数据库验证脚本
```

#### SQL_TYPE模式
```
sql/                    # 默认目录（ENABLE_SQL_TYPE_MODE=false）
├── shi/               # 市级SQL目录（SQL_TYPE=shi）
│   └── sql/
└── sheng/              # 省级SQL目录（SQL_TYPE=sheng）
    └── sql/
```

### 3. 执行脚本

#### Linux/macOS
```bash
# 标准模式（默认）
./upgrade.sh

# SQL_TYPE模式（需要修改脚本中的ENABLE_SQL_TYPE_MODE=true）
export JdexConsole_deploy_level=shi    # 或 sheng
./upgrade.sh
```

#### Windows
```batch
# 标准模式（默认）
upgrade.bat

# SQL_TYPE模式（需要修改脚本中的ENABLE_SQL_TYPE_MODE=true）
set JdexConsole_deploy_level=shi    # 或 sheng
upgrade.bat
```

## 配置参数说明

### 执行环境配置

| 参数 | 说明 | 默认值 | 可选值 |
|------|------|--------|--------|
| exec_env | 执行环境：host/docker | host | host, docker |
| docker_container | Docker容器名称 | - | 有效的容器名或ID |
| host | 数据库主机地址 | localhost | 有效的IP地址或主机名 |
| port | 数据库端口号 | 5432 | 1-65535 |
| user | 数据库用户名 | postgres | 有效的PostgreSQL用户名 |
| password | 数据库密码 | - | 对应用户的密码 |
| psql_path | psql命令路径 | - | 系统PATH中的psql或完整路径 |

### 执行控制配置

| 参数 | 说明 | 默认值 | 可选值 |
|------|------|--------|--------|
| dry_run | 预览模式，只显示不执行 | false | true, false |
| skip_confirm | 跳过确认提示 | true | true, false |
| db_only | 仅对指定数据库执行 | - | 数据库名称 |
| connect_timeout | 数据库连接超时时间(秒) | 5 | 正整数 |

### 目录配置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| sql_dir | SQL文件目录（占位符） | 'sql_dir_path' |
| file_pattern | SQL文件匹配模式 | '*.sql' |

### 版本控制配置

| 参数 | 说明 | 默认值 | 可选值 |
|------|------|--------|--------|
| enabled | 是否启用版本控制 | true | true, false |
| skip_executed | 是否跳过已执行文件 | true | true, false |

### 日志配置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| dir | 日志目录 | 'temp_log_path' |
| file | 日志文件名 | 'temp_log_name' |
| print_config | 是否打印配置信息 | true |

## 脚本内部控制变量

### ENABLE_SQL_TYPE_MODE
- **说明**：控制是否启用SQL_TYPE模式
- **默认值**：false（使用标准模式）
- **设置值**：true（启用SQL_TYPE模式）
- **修改位置**：upgrade.sh或upgrade.bat脚本内部

### SQL_TYPE（JdexConsole_deploy_level）
- **说明**：SQL升级级别，用于选择省级或市级SQL目录
- **取值**：
  - "shi"：使用市级SQL目录（$workdir/shi/sql）
  - "sheng"：使用省级SQL目录（$workdir/sheng/sql）
  - 其他值：使用默认SQL目录（./sql）

## 使用示例

### 1. 标准模式示例

```bash
# Linux/macOS
./upgrade.sh

# Windows
upgrade.bat
```

### 2. SQL_TYPE模式示例

```bash
# Linux/macOS - 市级
export JdexConsole_deploy_level=shi
# 修改脚本中的ENABLE_SQL_TYPE_MODE=true
./upgrade.sh

# Windows - 省级
set JdexConsole_deploy_level=sheng
# 修改脚本中的ENABLE_SQL_TYPE_MODE=true
upgrade.bat
```

### 3. 高级配置示例

```toml
# 生产环境配置
[database]
host = 'prod.db.company.com'
port = 5432
user = 'app_user'
password = 'secure_password'
exec_env = 'host'
psql_path = '/usr/local/bin/psql'

[execution]
dry_run = false
skip_confirm = false
connect_timeout = 10

[version]
enabled = true
skip_executed = true

[logging]
dir = '/var/log/sql-upgrade'
file = 'upgrade.log'
print_config = false
```

## 文件命名规范

### 分层目录命名
- **01_schema**：数据库模式定义，建表、建索引等
- **02_business**：业务逻辑相关SQL，插入初始数据等
- **03_validation**：验证脚本，检查数据完整性等

### SQL文件命名
建议使用数字前缀控制执行顺序：
```
001_create_database.sql
002_create_tables.sql
003_create_indexes.sql
004_insert_data.sql
005_create_views.sql
```

## 日志说明

### 日志位置
- **默认位置**：./logs/execute.log
- **自定义位置**：通过配置文件中的logging.dir和logging.file指定

### 日志格式
```
[2025-03-06 10:30:15] [INFO] PostgreSQL SQL 执行工具启动
[2025-03-06 10:30:15] [INFO] 执行环境: host
[2025-03-06 10:30:15] [INFO] 数据库连接成功
[2025-03-06 10:30:15] [INFO] 开始执行分层目录: 01_schema
[2025-03-06 10:30:15] [INFO] 数据库 postgres 已存在，跳过执行（请手动创建）
[2025-03-06 10:30:15] [INFO] 开始执行分层目录: 02_business
[2025-03-06 10:30:15] [INFO] 待执行SQL文件: 3
[2025-03-06 10:30:15] [INFO] 执行SQL文件: 001_create_tables.sql (Duration: 0.25s)
[2025-03-06 10:30:15] [INFO] 执行成功: 001_create_tables.sql (Duration: 0.25s)
[2025-03-06 10:30:15] [INFO] SQL upgrade execution completed!
```

## 故障排查

### 常见问题及解决方案

| 问题 | 可能原因 | 解决方案 |
|------|---------|----------|
| 数据库连接失败 | 主机地址、端口、用户名、密码错误 | 检查配置文件中的数据库连接参数 |
| psql命令未找到 | psql未安装或路径错误 | 安装PostgreSQL客户端或配置正确的psql_path |
| Docker容器连接失败 | 容器未运行或psql不可用 | 检查容器状态和容器内psql可用性 |
| SQL文件未找到 | sql_dir路径错误或文件名不匹配 | 检查SQL文件目录和文件命名 |
| 权限不足 | 文件或数据库访问权限不够 | 检查文件系统权限和数据库用户权限 |
| 字符集冲突 | 建库时字符集不兼容 | 使用template0模板建库 |

### 调试技巧

1. **启用详细日志**：
   ```toml
   [logging]
   print_config = true
   ```

2. **使用预览模式**：
   ```toml
   [execution]
   dry_run = true
   ```

3. **单数据库执行**：
   ```toml
   [execution]
   db_only = 'specific_database'
   ```

## 版本控制说明

### 版本文件
- **位置**：SQL目录下的version.txt
- **格式**：纯文本，每行一个版本号
- **作用**：控制当前执行的SQL版本

### 执行记录
- **全局记录**：记录所有数据库的执行状态
- **数据库记录**：记录每个数据库的详细执行历史
- **格式**：时间戳|阶段|数据库|文件名|状态

## 最佳实践

1. **SQL文件组织**：
   - 按功能模块分层组织
   - 使用数字前缀控制执行顺序
   - 每个SQL文件保持原子性

2. **版本管理**：
   - 每次升级创建新的版本号
   - 及时更新version.txt文件
   - 保留历史版本以便回滚

3. **生产环境使用**：
   - 设置skip_confirm=false，确保人工确认
   - 启用完整的日志记录
   - 使用适当的连接超时时间

4. **安全性考虑**：
   - 避免在配置文件中存储明文密码
   - 使用环境变量或密钥管理系统
   - 限制数据库用户权限

## 命令行工具

### 基本用法
```bash
# 使用配置文件执行
exec-sql -c config.toml

# 命令行模式
exec-sql --cmd-mode --host localhost --port 5432 --user postgres --db mydb
```

### 子命令

| 子命令 | 说明 |
|--------|------|
| check | 检查配置或环境变量 |
| replace | 替换配置文件中的占位符 |

### 高级参数

| 参数 | 说明 |
|------|------|
| --cmd-mode | 启用命令行模式 |
| --init-sql | 初始化SQL目录结构 |
| --init-config | 创建默认配置文件 |
| --db | 指定数据库名称 |
| --sql-dir | 指定SQL文件目录 |
| --dry-run | 预览模式，不实际执行 |

## 开发与扩展

### 项目结构
```
upgrade_sql/
├── go/                    # Go语言实现
│   ├── main.go           # 程序入口
│   ├── cmd/              # 命令行处理
│   ├── internal/          # 内部实现
│   │   ├── config/       # 配置管理
│   │   ├── core/         # 核心业务逻辑
│   │   ├── types/        # 类型定义
│   │   └── utils/        # 工具函数
│   └── go.mod/go.sum    # Go模块依赖
├── ExecuteSQL/            # 执行脚本和配置
│   ├── upgrade.sh/.bat   # 执行脚本
│   ├── config.toml      # 配置文件模板
│   └── sql/             # SQL文件目录
└── docs/                # 项目文档
```

### 扩展指南

1. **添加新的执行阶段**：
   - 在types.go中定义新的阶段常量
   - 在core.go中添加阶段处理逻辑
   - 更新DefaultExecutionStages切片

2. **自定义配置项**：
   - 在types.go中添加新的配置字段
   - 在config.go中添加验证逻辑
   - 更新DefaultConfig函数

3. **扩展数据库支持**：
   - 在database.go中添加新数据库的连接逻辑
   - 实现特定的SQL方言支持
   - 添加相应的测试用例

## 许可证

本项目采用开源许可证，具体请查看LICENSE文件。

## 贡献指南

欢迎提交Issue和Pull Request来改进项目。

1. **代码规范**：遵循Go语言编码规范
2. **提交规范**：使用清晰的提交信息
3. **测试要求**：确保新功能有相应的测试用例
4. **文档更新**：及时更新相关文档

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交Issue：[项目GitHub地址]
- 邮件联系：[维护者邮箱]