Skip to content

Latest commit

 

History

History
464 lines (332 loc) · 9.67 KB

SQL_EXPORT_GUIDE.md

File metadata and controls

464 lines (332 loc) · 9.67 KB

SQL 导出功能详解

📊 功能概述

Excel CLI 支持将 Excel 数据导出为 SQL INSERT 语句，方便直接导入到数据库。

🗄️ 支持的 SQL 方言

方言 别名 标识符引用 示例
MySQL mysql, mariadb `column` `user_name`
PostgreSQL postgresql, postgres, pg "column" "user_name"
SQLite sqlite, sqlite3 "column" "user_name"
SQL Server sqlserver, mssql, tsql [column] [user_name]
Oracle oracle "COLUMN" "USER_NAME"

🚀 基本使用

1. 最简单的用法

excel-cli convert -i data.xlsx -o output.sql -f sql --sql-table users

说明：

  • 默认使用 MySQL 方言
  • 使用 Excel 中的原始列名
  • 生成批量 INSERT 语句（每批 1000 行）

2. 指定 SQL 方言

# PostgreSQL
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-dialect postgresql \
  --sql-table users

# SQLite
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-dialect sqlite \
  --sql-table users

# SQL Server
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-dialect sqlserver \
  --sql-table users

🏷️ 列名映射

为什么需要列名映射？

Excel 中的列名可能包含：

  • 中文字符
  • 空格
  • 特殊符号
  • 不符合数据库命名规范的字符

数据库列名通常需要：

  • 使用英文字母、数字和下划线
  • 遵循命名规范（如 snake_case）

使用列名映射

假设 Excel 有以下列：

姓名 年龄 所在城市
张三 30 北京
李四 25 上海

映射到数据库列名：

excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users \
  --sql-dialect mysql \
  --column-mapping "user_name,user_age,user_city"

注意：

  • 列名映射必须用逗号分隔
  • 映射的列名数量必须与 Excel 列数完全相同
  • 列名顺序与 Excel 列顺序对应

验证列名映射

工具会自动验证并显示映射关系：

$ excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users \
  --column-mapping "user_name,user_age,user_city"

📖 正在读取 Excel 文件: data.xlsx
✅ 成功读取工作表 'Sheet1': 2 行 × 3 列
📋 列名映射:
   姓名 -> user_name
   年龄 -> user_age
   所在城市 -> user_city
🗄️  SQL 方言: mysql
📊 表名: users
📝 正在导出为 SQL 格式...
✅ 转换完成! 输出文件: output.sql

📝 输出示例

MySQL 输出

-- Generated by excel-cli
-- Dialect: MySQL
-- Table: users
-- Rows: 2

INSERT INTO `users` (`user_name`, `user_age`, `user_city`) VALUES
('张三', 30, '北京'),
('李四', 25, '上海');

PostgreSQL 输出

-- Generated by excel-cli
-- Dialect: PostgreSQL
-- Table: users
-- Rows: 2

INSERT INTO "users" ("user_name", "user_age", "user_city") VALUES
('张三', 30, '北京'),
('李四', 25, '上海');

SQL Server 输出

-- Generated by excel-cli
-- Dialect: SqlServer
-- Table: users
-- Rows: 2

INSERT INTO [users] ([user_name], [user_age], [user_city]) VALUES ('张三', 30, '北京');
INSERT INTO [users] ([user_name], [user_age], [user_city]) VALUES ('李四', 25, '上海');

注意： SQL Server 和 Oracle 使用单条 INSERT 语句，而不是批量 INSERT。

Oracle 输出

-- Generated by excel-cli
-- Dialect: Oracle
-- Table: users
-- Rows: 2

INSERT INTO "USERS" ("USER_NAME", "USER_AGE", "USER_CITY") VALUES ('张三', 30, '北京');
INSERT INTO "USERS" ("USER_NAME", "USER_AGE", "USER_CITY") VALUES ('李四', 25, '上海');

注意： Oracle 会自动将表名和列名转换为大写。

🎯 数据类型处理

字符串

-- 自动添加单引号并转义
'Hello World'
'It''s a test'  -- 单引号被转义为两个单引号

数字

-- 整数
42

-- 浮点数
3.14

-- 科学计数法自动转换
1000000  -- 而不是 1e6

布尔值

方言 TRUE FALSE
MySQL 1 0
PostgreSQL TRUE FALSE
SQLite 1 0
SQL Server 1 0
Oracle 1 0

空值

所有方言统一使用 NULL

📊 完整示例

示例 1: 用户表

Excel 数据 (users.xlsx):

用户名 年龄 邮箱 是否激活
alice 30 alice@example.com TRUE
bob 25 bob@example.com FALSE
charlie 35 TRUE

命令:

excel-cli convert -i users.xlsx -o users.sql -f sql \
  --sql-dialect mysql \
  --sql-table users \
  --column-mapping "username,age,email,is_active"

输出 (users.sql):

-- Generated by excel-cli
-- Dialect: MySQL
-- Table: users
-- Rows: 3

INSERT INTO `users` (`username`, `age`, `email`, `is_active`) VALUES
('alice', 30, 'alice@example.com', 1),
('bob', 25, 'bob@example.com', 0),
('charlie', 35, NULL, 1);

示例 2: 产品表

Excel 数据 (products.xlsx):

产品名称 价格 库存 描述
笔记本电脑 5999.99 50 高性能笔记本
鼠标 89.00 200 无线鼠标

命令:

excel-cli convert -i products.xlsx -o products.sql -f sql \
  --sql-dialect postgresql \
  --sql-table products \
  --column-mapping "product_name,price,stock,description"

输出 (products.sql):

-- Generated by excel-cli
-- Dialect: PostgreSQL
-- Table: products
-- Rows: 2

INSERT INTO "products" ("product_name", "price", "stock", "description") VALUES
('笔记本电脑', 5999.99, 50, '高性能笔记本'),
('鼠标', 89, 200, '无线鼠标');

⚠️ 常见错误

错误 1: 列名映射数量不匹配

$ excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users \
  --column-mapping "name,age"

❌ 错误: 列名映射数量(2)与 Excel 列数(3)不匹配
Excel 列名: ["姓名", "年龄", "城市"]
映射列名: ["name", "age"]

解决方法： 确保列名映射数量与 Excel 列数完全相同

excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users \
  --column-mapping "name,age,city"

错误 2: 不支持的 SQL 方言

$ excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-dialect db2 \
  --sql-table users

Error: 不支持的 SQL 方言: db2

解决方法： 使用支持的方言之一：mysql, postgresql, sqlite, sqlserver, oracle

错误 3: 缺少表名

$ excel-cli convert -i data.xlsx -o output.sql -f sql

# 会使用默认表名 "table_name"，建议明确指定

最佳实践： 始终使用 --sql-table 明确指定表名

💡 最佳实践

1. 使用列名映射

即使 Excel 列名是英文，也建议使用列名映射来标准化命名：

# 推荐
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users \
  --column-mapping "user_id,user_name,created_at"

# 不推荐（使用 Excel 原始列名）
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users

2. 选择合适的方言

根据目标数据库选择正确的方言：

# 开发环境用 SQLite
excel-cli convert -i data.xlsx -o dev.sql -f sql \
  --sql-dialect sqlite \
  --sql-table users

# 生产环境用 PostgreSQL
excel-cli convert -i data.xlsx -o prod.sql -f sql \
  --sql-dialect postgresql \
  --sql-table users

3. 验证生成的 SQL

导入前先检查生成的 SQL 文件：

# 生成 SQL
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sql-table users \
  --column-mapping "id,name,age"

# 检查前几行
head -n 20 output.sql

# 或在 PowerShell 中
Get-Content output.sql -Head 20

4. 分批处理大文件

对于大型 Excel 文件，可以：

  1. 先导出一部分数据测试
  2. 确认无误后导出全部数据
  3. 考虑使用数据库的批量导入工具（如 LOAD DATA）

5. 处理特殊字符

如果数据包含特殊字符（如单引号），工具会自动转义：

-- 原始数据: It's a test
-- 转义后: 'It''s a test'

🔧 高级用法

组合使用工作表选择

# 只导出特定工作表
excel-cli convert -i data.xlsx -o output.sql -f sql \
  --sheet "Users" \
  --sql-table users \
  --sql-dialect mysql \
  --column-mapping "user_id,user_name,user_email"

批处理脚本

PowerShell:

# 批量转换多个 Excel 文件为 SQL
Get-ChildItem *.xlsx | ForEach-Object {
    $name = $_.BaseName
    excel-cli convert -i $_.Name -o "$name.sql" -f sql `
        --sql-table $name `
        --sql-dialect mysql
}

Bash:

# 批量转换多个 Excel 文件为 SQL
for file in *.xlsx; do
    name="${file%.xlsx}"
    excel-cli convert -i "$file" -o "$name.sql" -f sql \
        --sql-table "$name" \
        --sql-dialect postgresql
done

📚 导入数据库

生成 SQL 文件后，可以使用以下命令导入：

MySQL

mysql -u username -p database_name < output.sql

PostgreSQL

psql -U username -d database_name -f output.sql

SQLite

sqlite3 database.db < output.sql

SQL Server

sqlcmd -S server_name -d database_name -i output.sql

❓ 常见问题

Q: 支持 UPDATE 或 DELETE 语句吗？

A: 目前只支持 INSERT 语句。UPDATE 和 DELETE 可能在未来版本中添加。

Q: 可以自定义批量大小吗？

A: 目前批量大小固定为 1000 行。未来可能添加自定义选项。

Q: 支持日期时间格式吗？

A: 日期时间会被转换为字符串格式。建议在数据库中使用 STR_TO_DATE() 或类似函数转换。

Q: 如何处理包含 NULL 的数据？

A: Excel 中的空单元格会自动转换为 SQL 的 NULL。

更多信息请参考 README.md 和 EXAMPLES.md。