pg2sqlite

🚀 高性能 PostgreSQL 到 SQLite 转换工具

功能特性

✅ 批量数据转换: 支持大批量数据的高效转换
✅ 多表并行处理: 同时转换多个表，提高效率
✅ 自动数据类型转换: 智能转换 PostgreSQL 到 SQLite 数据类型
✅ 进度跟踪: 实时显示转换进度和统计信息
✅ 错误重试机制: 自动重试失败的转换操作
✅ 配置文件支持: 灵活的 YAML 配置文件
✅ 命令行参数: 支持命令行参数覆盖配置
✅ 跨平台支持: 支持 Linux、Windows、macOS
✅ 索引策略优化: 支持多种索引创建策略
✅ SQLite性能优化: 自动应用SQLite性能优化设置
✅ SSL自动回退: 优先使用SSL连接，失败时自动回退到非SSL
✅ 动态Schema支持: 支持自定义PostgreSQL schema
✅ 动态约束读取: 自动从PostgreSQL读取约束信息
✅ 表发现模式: 支持自动、手动、混合三种表发现模式
✅ 安全特性: 密码掩码、输入验证、文件权限检查
✅ 版本管理: 内置版本信息和构建信息
✅ 任务分配器: 智能任务分配，确保数据完整性

⚠️ 重要警告

在开始数据转换之前，请务必仔细阅读以下警告信息：

🚨 数据转换风险

数据丢失风险
- 转换过程中可能出现数据丢失、损坏或格式错误
- 建议在转换前完整备份原始PostgreSQL数据库
- 在生产环境使用前，请先在测试环境验证转换结果
数据类型兼容性
- PostgreSQL和SQLite之间存在数据类型差异
- 某些PostgreSQL特有功能（如数组、JSONB等）可能无法完全转换
- 日期时间格式、数值精度可能发生变化
约束和索引
- 外键约束、检查约束等可能无法完全转换
- 复合索引、部分索引等高级索引可能不支持
- 转换后的查询性能可能与原数据库不同
大文件处理
- 超大数据库文件可能导致内存不足或磁盘空间不足
- 转换过程可能耗时很长，请确保有足够的处理时间
- 建议分批处理超大数据集

🛡️ 安全建议

权限控制
- 确保对源数据库和目标文件有适当的读写权限
- 避免在公共网络环境中传输敏感数据
- 使用环境变量存储数据库密码，避免在配置文件中明文存储
数据验证
- 转换完成后，请自行验证数据完整性和准确性
- 对比关键数据记录的条数和内容
- 测试关键查询语句的执行结果
回滚准备
- 保留原始数据库的完整备份
- 记录转换过程中的关键参数和配置
- 准备数据恢复和回滚方案

📋 使用前检查清单

已备份原始PostgreSQL数据库
已测试数据库连接和权限
已检查目标磁盘空间是否充足
已了解数据类型转换的潜在影响
已制定数据验证和测试计划
已准备回滚和恢复方案

使用本工具即表示您已充分了解上述风险，并同意自行承担数据转换过程中的所有责任。

快速开始

1. 下载和安装

方式一：下载预编译版本（推荐）

从 Releases 页面下载适合您系统的预编译版本：

Windows: pg2sqlite-windows-amd64.exe
Linux: pg2sqlite-linux-amd64
macOS: pg2sqlite-darwin-amd64

下载后重命名为 pg2sqlite.exe（Windows）或 pg2sqlite（Linux/macOS）。

方式二：从源码构建

如果您需要自定义构建或最新版本：

# 克隆仓库
git clone https://github.com/hillghost86/pg2sqlite.git
cd pg2sqlite

# 安装依赖
go mod tidy

# 构建
go build -o pg2sqlite.exe .  # Windows
go build -o pg2sqlite .       # Linux/macOS

2. 选择配置文件

我们提供了4个预设配置文件，根据您的需求选择：建议使用完整配置来修改你需要修改的信息。

# 直接运行 需要在config目录下有config.yaml文件。可以直接复制项目config目录下的config.yaml文件进行修改。
./pg2sqlite.exe 

# 完整配置 (推荐自行自定义修改)
./pg2sqlite.exe --config config/config.yaml

# 快速开始 (推荐首次使用)
./pg2sqlite.exe --config config/quick_start.yaml

# 高性能转换 (推荐生产环境)
./pg2sqlite.exe --config config/high_performance.yaml

# 测试功能 (推荐开发测试)
./pg2sqlite.exe --config config/test_config.yaml

3. 配置数据库连接

编辑选定的配置文件，修改数据库连接信息：

database:
  postgresql:
    host: "您的PostgreSQL服务器"     # 修改为您的服务器地址
    port: 5432                      # 修改为您的端口
    database: "您的数据库名"         # 修改为您的数据库名
    username: "您的用户名"           # 修改为您的用户名
    password: ""                    # 修改为您的密码（建议使用环境变量 PG2SQL_PASSWORD）
    ssl_mode: "prefer"              # SSL模式：prefer/disable/require
    schema: "public"                 # 数据库schema
  
  sqlite:
    path: "输出文件.db"              # 修改为您想要的SQLite文件路径
    journal_mode: "WAL"             # 日志模式：WAL/DELETE/MEMORY/OFF

4. 运行转换

# 使用默认配置文件
./pg2sqlite.exe 

# 使用配置文件
./pg2sqlite.exe --config config/config.yaml

# 使用命令行参数覆盖配置
./pg2sqlite.exe --config config/config.yaml --test-limit 1000000

📁 配置文件说明

项目提供了4个预设配置文件，位于 config/ 目录：

1. config.yaml - 完整配置文件 ⭐

包含所有配置项的详细说明
适合深入了解所有配置选项
包含详细的注释和推荐值
推荐: 作为配置参考和自定义配置的基础

2. quick_start.yaml - 快速开始配置 🚀

简化的配置文件
只需要修改数据库连接信息
使用推荐设置
推荐: 首次使用和快速开始

3. high_performance.yaml - 高性能配置 ⚡

针对大数据量优化
适用于1000万+记录转换
最大化插入性能
推荐: 生产环境大数据量转换

4. test_config.yaml - 测试配置 🧪

限制数据量进行测试
包含索引创建
适合功能验证
推荐: 开发测试和功能验证

配置文件结构

# 数据库配置
database:
  postgresql:
    host: "localhost"
    port: 5432
    database: "mydb"
    username: "user"
    password: "password"
    ssl_mode: "disable"
  
  sqlite:
    path: "/path/to/output.db"
    journal_mode: "WAL"  # WAL/DELETE/MEMORY/OFF

# 转换配置
conversion:
  tables:
    - name: "users"
      where_clause: "created_at > '2023-01-01'"
      indexes:
        - name: "idx_users_email"
          columns: ["email"]
          unique: true
  
  # 性能调优
  batch_size: 5000              # 批处理大小
  max_workers: 8                # 最大并发工作协程数
  test_limit: 0                 # 测试数据限制 (0=无限制)
  
  # 文件处理
  drop_existing: true           # 是否删除现有表
  skip_existing: false          # 是否跳过现有表
  backup_file: ""               # 备份文件路径
  
  # 索引策略
  index:
    create_timing: "after"      # 索引创建时机: before/after/after_all/none
    batch_size: 1000            # 批量创建索引的批次大小
    skip_unsupported: true      # 跳过不支持的索引类型
    optimize_for: "insert"      # 优化目标: query/insert/balanced
  
  # 错误处理
  retry_count: 3                # 重试次数
  retry_delay: "1s"             # 重试延迟
  
  # 数据类型转换
  data_type_conversion:
    show_report: false          # 是否显示数据类型转换报告
    custom_mappings: {}         # 自定义类型映射
    strict_mode: false          # 严格模式
  
  # 进度和日志
  progress_log: true            # 是否显示进度日志

# 日志配置
logging:
  level: "info"                 # 日志级别: debug/info/warn/error
  format: "text"                # 日志格式: text/json
  file: ""                      # 日志文件路径

📋 Tables 配置详解

tables 是一个数组，每个元素代表一个要转换的表，包含以下配置项：

1. `name` - 表名 ⭐

name: "addresses"

作用: 指定要转换的PostgreSQL表名
必需: ✅ 必须配置
示例:
- "users" - 用户表
- "orders" - 订单表
- "products" - 产品表
- "addresses" - 地址表

2. `where_clause` - WHERE条件 🔍

where_clause: "id > 1000"

作用: 指定数据过滤条件，只转换满足条件的记录
必需: ❌ 可选配置
默认值: "" (空字符串，转换所有记录)
示例:
- "" - 转换所有记录
- "id > 1000" - 只转换ID大于1000的记录
- "created_at > '2023-01-01'" - 只转换2023年后的记录
- "status = 'active' AND deleted_at IS NULL" - 只转换活跃且未删除的记录

3. `indexes` - 索引配置 🗂️

indexes:
  - name: "idx_addresses_address"
    columns: ["address"]
    unique: false
  - name: "idx_addresses_chain_id"
    columns: ["chain_id"]
    unique: false

作用: 为转换后的SQLite表创建索引
必需: ❌ 可选配置
默认值: [] (空数组，不创建索引)

索引配置项:

`name` - 索引名称

name: "idx_addresses_address"

作用: 索引的唯一名称
命名建议: 使用 idx_表名_列名 格式
示例: "idx_users_email", "idx_orders_created_at"

`columns` - 索引列

columns: ["address"]
columns: ["chain_id", "address"]  # 复合索引

作用: 指定要创建索引的列名
支持: 单列索引和复合索引
示例:
- ["email"] - 单列索引
- ["user_id", "created_at"] - 复合索引

`unique` - 唯一性约束

unique: false  # 普通索引
unique: true   # 唯一索引

作用: 指定是否为唯一索引
默认值: false
说明:
- false - 普通索引，允许重复值
- true - 唯一索引，不允许重复值

📝 Tables 配置示例

示例1: 简单表转换

tables:
  - name: "users"
    where_clause: ""
    indexes: []

示例2: 条件过滤转换

tables:
  - name: "orders"
    where_clause: "status = 'completed' AND created_at > '2023-01-01'"
    indexes: []

示例3: 带索引转换

tables:
  - name: "products"
    where_clause: "active = true"
    indexes:
      - name: "idx_products_name"
        columns: ["name"]
        unique: false
      - name: "idx_products_category"
        columns: ["category_id"]
        unique: false
      - name: "idx_products_sku"
        columns: ["sku"]
        unique: true

示例4: 多表转换

tables:
  - name: "users"
    where_clause: "deleted_at IS NULL"
    indexes:
      - name: "idx_users_email"
        columns: ["email"]
        unique: true
      - name: "idx_users_created_at"
        columns: ["created_at"]
        unique: false
  
  - name: "orders"
    where_clause: "status IN ('pending', 'processing')"
    indexes:
      - name: "idx_orders_user_id"
        columns: ["user_id"]
        unique: false
      - name: "idx_orders_status_created"
        columns: ["status", "created_at"]
        unique: false
  
  - name: "order_items"
    where_clause: ""
    indexes: []

🎯 Tables 使用场景

1. 全表转换

tables:
  - name: "addresses"
    where_clause: ""
    indexes: []

适用: 需要转换整个表的所有数据
特点: 数据完整，转换时间较长

2. 增量转换

tables:
  - name: "addresses"
    where_clause: "updated_at > '2023-12-01'"
    indexes: []

适用: 只转换最近更新的数据
特点: 数据量小，转换速度快

3. 查询优化转换

tables:
  - name: "addresses"
    where_clause: ""
    indexes:
      - name: "idx_addresses_address"
        columns: ["address"]
        unique: false

适用: 转换后需要频繁查询
特点: 查询速度快，但转换时间稍长

4. 数据清理转换

tables:
  - name: "addresses"
    where_clause: "deleted_at IS NULL AND status = 'active'"
    indexes: []

适用: 只转换有效数据，过滤无效记录
特点: 数据质量高，存储空间小

⚠️ Tables 配置注意事项

1. 表名大小写

PostgreSQL表名区分大小写
如果表名包含大写字母，需要用双引号包围
示例: name: "UserProfiles"

2. WHERE条件语法

使用PostgreSQL的SQL语法
注意日期格式和字符串转义
示例: where_clause: "created_at > '2023-01-01'::date"

3. 索引创建时机

索引创建受 conversion.index.create_timing 控制
可以选择在插入前、插入后或全部完成后创建
大数据量建议使用 "after_all" 策略

4. 性能考虑

索引会减慢插入速度，但提高查询速度
复合索引的顺序很重要
避免创建过多不必要的索引

🚀 Tables 最佳实践

1. 索引命名规范

# 推荐命名格式
name: "idx_表名_列名"
name: "idx_users_email"
name: "idx_orders_user_created"

2. 条件过滤优化

# 使用索引列进行过滤
where_clause: "user_id > 1000"  # 如果user_id有索引

# 避免使用函数
where_clause: "created_at > '2023-01-01'"  # 推荐
where_clause: "DATE(created_at) = '2023-01-01'"  # 不推荐

3. 复合索引设计

# 查询条件: WHERE user_id = ? AND status = ?
indexes:
  - name: "idx_orders_user_status"
    columns: ["user_id", "status"]  # 顺序很重要
    unique: false

命令行参数

参数	说明	默认值
`--config`	配置文件路径	`config.yaml`
`--pg-host`	PostgreSQL 主机	-
`--pg-port`	PostgreSQL 端口	`5432`
`--pg-database`	PostgreSQL 数据库名	-
`--pg-username`	PostgreSQL 用户名	-
`--pg-password`	PostgreSQL 密码	-
`--sqlite-path`	SQLite 文件路径	-
`--batch-size`	批处理大小	`1000`
`--max-workers`	最大工作协程数	`4`
`--test-limit`	测试数据限制	`0`
`--drop-existing`	删除现有表	`false`
`--progress-log`	显示进度日志	`true`

开发构建

如果您需要从源码构建或开发版本：

Linux/macOS

chmod +x build.sh
./build.sh

Windows

build.bat

构建完成后，二进制文件位于 build/ 目录。

手动构建

# 安装依赖
go mod tidy

# 构建
go build -o pg2sqlite.exe .  # Windows
go build -o pg2sqlite .       # Linux/macOS

# 构建时注入版本信息
go build -ldflags "-X pg2sqlite/internal/config.Version=1.0.0 -X pg2sqlite/internal/config.BuildTime=$(date -u +%Y-%m-%d)" -o pg2sqlite.exe .

数据类型转换

PostgreSQL	SQLite	说明
`bigint`, `int8`	`INTEGER`	64位整数
`integer`, `int4`	`INTEGER`	32位整数
`smallint`, `int2`	`INTEGER`	16位整数
`real`, `float4`	`REAL`	单精度浮点数
`double precision`, `float8`	`REAL`	双精度浮点数
`numeric`, `decimal`	`REAL`	精确数值
`boolean`, `bool`	`INTEGER`	布尔值 (0/1)
`varchar`, `text`	`TEXT`	文本
`timestamp`	`TEXT`	时间戳
`date`	`TEXT`	日期
`json`, `jsonb`	`TEXT`	JSON
`uuid`	`TEXT`	UUID
`bytea`	`BLOB`	二进制数据

性能优化

1. 批处理大小调优

根据数据量和内存情况调整 batch_size：

小表 (< 100万记录): 1000-5000
中表 (100万-1000万记录): 5000-10000
大表 (> 1000万记录): 10000-50000

2. 并发调优

根据 CPU 核心数调整 max_workers：

CPU 密集型: CPU核心数
IO 密集型: CPU核心数 * 2-4

3. 索引策略优化

选择适合的索引创建时机：

"before": 插入前创建 (小数据量)
"after": 插入后创建 (推荐)
"after_all": 全部完成后创建 (大数据量)
"none": 不创建索引 (最快)

4. SQLite性能优化

工具自动应用以下SQLite优化设置：

WAL模式: 提高并发性能
大缓存: 500MB内存缓存 (可配置)
大页面: 32KB页面大小 (可配置)
内存映射: 2GB内存映射 (可配置)
内存临时存储: 临时数据存储在内存中
连接池优化: 动态调整PostgreSQL连接池
预编译语句: 使用预编译语句提高插入性能
子批处理: 自动处理SQLite变量限制

📊 性能对比

配置文件	批次大小	并发数	索引策略	适用场景	预计时间(7000万条)
quick_start	5000	8	无索引	快速开始	~30分钟
high_performance	10000	16	全部完成后	生产环境	~20分钟
test_config	5000	8	插入后	开发测试	限制100万条

错误处理

工具内置了完善的错误处理机制：

连接重试: 自动重试数据库连接
批次重试: 失败的批次会自动重试
优雅退出: 支持 Ctrl+C 安全退出
详细日志: 记录详细的错误信息和堆栈

示例用法

转换单个表

./pg2sqlite.exe \
  --config config/quick_start.yaml \
  --pg-host localhost \
  --pg-database mydb \
  --pg-username user \
  --pg-password pass \
  --sqlite-path output.db \
  --batch-size 5000

转换多个表

conversion:
  tables:
    - name: "users"
    - name: "orders"
    - name: "products"
      where_clause: "status = 'active'"

条件转换

conversion:
  tables:
    - name: "logs"
      where_clause: "created_at > '2023-01-01' AND level = 'ERROR'"

测试模式

# 限制100万条记录进行测试
./pg2sqlite.exe --config config/test_config.yaml --test-limit 1000000

🎯 使用建议

配置文件选择指南:

🚀 首次使用: 使用 config.yaml（完整配置）
- 包含所有配置项的详细说明
- 只需要修改数据库连接信息
- 使用推荐设置
- 推荐: 作为配置参考和自定义配置的基础
⚡ 快速开始: 使用 quick_start.yaml
- 简化的配置文件
- 只需要修改数据库连接信息
- 使用推荐设置
- 推荐: 首次使用和快速开始
🧪 开发测试: 使用 test_config.yaml
- 限制数据量进行测试
- 包含索引创建
- 适合功能验证
- 推荐: 开发测试和功能验证
🔥 生产环境: 使用 high_performance.yaml
- 针对大数据量优化
- 最大化插入性能
- 适用于1000万+记录
- 推荐: 生产环境大数据量转换

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

🔧 高级功能

1. SSL自动回退机制

database:
  postgresql:
    ssl_mode: "prefer"  # 优先使用SSL，失败时自动回退到非SSL

2. 动态Schema支持

database:
  postgresql:
    schema: "public"  # 支持自定义schema，默认为"public"

3. 表发现模式

conversion:
  table_discovery:
    mode: "auto"  # auto/manual/hybrid
    exclude_patterns: ["temp_*", "log_*"]
    min_rows: 1000

4. 安全特性

密码掩码: 日志中自动隐藏密码信息
输入验证: 验证数据库标识符安全性
文件权限检查: 检查SQLite文件权限安全性
环境变量支持: 支持通过环境变量传递敏感信息

5. 版本管理

# 查看版本信息
./pg2sqlite.exe version

# 构建时注入版本信息
go build -ldflags "-X pg2sqlite/internal/config.Version=1.0.0 -X pg2sqlite/internal/config.BuildTime=2025-01-12"

更新日志

v1.0.0 (2025-01-12)

🎉 初始版本发布
✅ 核心功能: PostgreSQL 到 SQLite 转换
✅ 高性能: 并行处理、批处理优化
✅ SSL自动回退: 优先SSL，失败时回退非SSL
✅ 动态Schema支持: 支持自定义PostgreSQL schema
✅ 动态约束读取: 自动从PostgreSQL读取约束信息
✅ 表发现模式: 支持自动、手动、混合三种模式
✅ 安全特性: 密码掩码、输入验证、文件权限检查
✅ 版本管理: 内置版本信息和构建信息
✅ 任务分配器: 智能任务分配，确保数据完整性
✅ SQLite性能优化: 可配置的性能参数
✅ 连接池优化: 动态调整PostgreSQL连接池
✅ 预编译语句: 提高插入性能
✅ 子批处理: 自动处理SQLite变量限制
✅ 配置文件: 4种预设配置文件
✅ 跨平台支持: Windows、Linux、macOS
✅ 详细文档: 完整的使用指南

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
config		config
examples		examples
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
VERSION.md		VERSION.md
build.bat		build.bat
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation