sqlite2pg

SQLite to PostgreSQL数据迁移工具

English

一个基于 Go 语言编写的高效数据迁移工具，用于将本地 SQLite 数据库中的数据流式导出并导入到 PostgreSQL（完全兼容 Neon Serverless Postgres、Supabase 等云原生数据库）。

💡 核心特性

• 深度数据类型兼容转换：
  • 布尔值转化：自动识别 "1"/"0", "true"/"false", "t"/"f" 并转为 PG 的 boolean。
  • 时间格式解析：自动匹配 ISO8601、RFC3339、YYYY-MM-DD HH:MM:SS 以及 10位/13位 Unix 秒/毫秒时间戳字符串，转化为 PG timestamp。
  • JSON 校验：识别文本中的合规 JSON 结构，确保直接写入 PG 的 json/jsonb 列。
• 云原生 / Neon 优化：
  • 支持直接填入 Neon DSN 字符串，默认强制开启 sslmode=require。
  • 优化连接池控制，内置重试机制应对 Neon/Serverless 实例冷启动。
• 动态全表迁移：支持通过 YAML 指定要迁移的表，或者留空自动提取 SQLite 中的所有业务表（自动过滤 sqlite_* 系统表）。
• 高性能 & 低内存占用：通过游标逐行读取、PreparedStatement 与批量事务提交（Batch Commit），避免大表一次性加载导致的内存溢出（OOM）。

---

📁 项目目录结构

.
├── bin                   # 二进制程序目录
├── build                 # 构建输出目录
├── cmd                   # 迁移工具核心代码  
│   └── main.go           # 迁移工具核心执行逻辑  
├── config.yaml           # 数据库与迁移配置文件, 复制config.yaml.example 到项目根目录
├── config.yaml.example   # 示例配置文件        
├── go.mod         # Go 模块文件
├── LICENSE        # 授权协议
├── Makefile       # 构建脚本
├── README.md      # 英文说明
├── README_zh.md   # 中文说明
└── scripts        # 构建脚本
    └── build.sh

快速开始

1. 环境准备与依赖安装

1.1. 克隆项目代码

git clone https://github.com/bodii/sqlite2pg.git

1.2. 确保本地已安装 Go 1.18+ 环境，并在项目根目录下执行： 引入所需要的依赖包

go mod tidy

# 或 手动安装依赖包
go get modernc.org/sqlite
go get github.com/lib/pq
go get gopkg.in/yaml.v3

注意：由于使用了 go-sqlite3（使用了 CGO），本地开发构建环境需确保已安装 gcc 或 clang

2. 提前在目标 PostgreSQL 中建表 (DML vs DDL)

迁移工具仅负责数据传输与数据类型强兼容转换（DML），不负责在 PostgreSQL 中创建表结构（DDL）。请在执行迁移前，确保 PostgreSQL / Neon 数据库中已经提前初始化好了对应的数据库 Schema（建议使用 ORM、golang-migrate 或直接导出的 SQL 脚本先行创建空表）。

⚙️ 配置文件说明

(config.yaml)在项目根目录下配置 config.yaml 文件：YAML# SQLite 源数据库配置

1. 复制配置文件 config.yaml.example 为 config.yaml

   cp config.yaml.example config.yaml

2. 根据实际情况修改配置文件中的数据库连接信息 ```yaml sqlite: db_path: “./source.db”

PostgreSQL / Neon 目标数据库配置

postgres:

优先推荐使用完整的 DSN 连接串 (可在 Neon Dashboard 一键复制)

dsn: “postgres://user:password@ep-sample-123456.us-east-2.aws.neon.tech/neondb?sslmode=require”

如果 dsn 设为空字符串 “”，程序会自动解析并使用以下分拆参数

host: “ep-sample-123456.us-east-2.aws.neon.tech” port: 5432 user: “postgres” password: “your_password” dbname: “neondb” sslmode: “require” # Neon 数据库通常强制要求 sslmode=require channel_binding: “require”

是否禁用外键约束，如果有关性外键约束，建议将此参数设为 true

foreign_keys: false

是否清空目标表数据，如果设为 true，将先清空原有目标表数据；false将保留目标表数据，以追加的方式

truncate_tables: false

迁移任务相关参数配置

migration: batch_size: 1000

需要迁移的表名列表；若设为 [] 或直接注释，将自动扫描 SQLite 中的全部表

tables: []

## 🚀 运行迁移脚本

> 运行迁移脚本有三种方式：

#### 1. 直接运行
配置完成后，直接在终端运行主程序即可：
```bash
go run cmd/main.go config.yaml

# 或 在配置文件名是config.yaml 时运行
go run cmd/main.go

2. 打包编译并运行

1. 编译为二进制文件 ```bash

   make build

   make build-binary

or script build.sh

bash ./scripts/build.sh

2. 复制编译好的二进制程序文件到项目根目录下
```bash
# Linux/macOS
cp -f ./build/sqlite2pg-linux-amd64 ./bin/sqlite2pg

# Windows
cp -f ./build/sqlite2pg-windows-amd64.exe ./bin/sqlite2pg.exe

3. 运行二进制程序 ```bash

   Linux/macOS 运行二进制程序

   ./bin/sqlite2pg config.yaml

或 Windows 运行已编译的二进制程序

./bin/sqlite2pg.exe config.yaml

#### 3. 下载二进制程序文件运行
linux/macOS 下：

curl -L https://github.com/bodii/sqlite2pg/releases/latest/download/sqlite2pg_linux_amd64 -o sqlite2pg

./bin/sqlite2pg config.yaml

windows 下：

curl -L https://github.com/bodii/sqlite2pg/releases/latest/download/sqlite2pg_windows_amd64.exe -o sqlite2pg.exe

./bin/sqlite2pg.exe config.yaml

控制台输出示意：
```text
2026/08/21 17:45:00 正在连接到 PostgreSQL / Neon 数据库...
2026/08/21 17:45:01 数据库连接成功！
2026/08/21 17:45:01 未指定 migration.tables，正在自动扫描 SQLite 中所有业务表...
2026/08/21 17:45:01 扫描完成，共获取到 3 张表: [users orders products]
2026/08/21 17:45:01 --> 开始迁移表: users
2026/08/21 17:45:01 ==> 成功完成表 [users] 迁移，共计导入 250 条记录
2026/08/21 17:45:01 --> 开始迁移表: orders
2026/08/21 17:45:02     [orders] 已处理 1000 条记录...
2026/08/21 17:45:03 ==> 成功完成表 [orders] 迁移，共计导入 1850 条记录
2026/08/21 17:45:03 数据迁移任务处理完毕！

🔄 核心数据兼容转换规则

SQLite 数据表现形式	转换目标类型 (PostgreSQL)	转换机制与说明
“1”, “0”, “true”, “false”, “t”, “f”	boolean	不区分大小写匹配，转为布尔类型，防止 PG 字段类型校验失败
“2026-08-21 17:45:00”	timestamp	ISO8601, RFC3339
“2026-08-21 17:45:00”	timestamp	YYYY-MM-DD HH:MM:SS
“1787251409”	timestamp	秒级 Unix 时间戳
“1787251409123”	timestamp	毫秒级 Unix 时间戳
{“key”: “val”} 或 [1, 2, 3]	json / jsonb	校验格式为合法 JSON 文本后直接传送给 PG 引擎解析

📌 迁移后步骤：重置 PostgreSQL 自增序列

如果迁移的表在 PostgreSQL 中使用了 SERIAL、BIGSERIAL 或 GENERATED BY DEFAULT AS IDENTITY 自增主键，迁移工具在导入数据时会带入 SQLite 原有的自增主键 id。 这会导致 PostgreSQL 的自增序列（Sequence）未跟随当前最大 id 递增。为防止后续新增记录时触发 主键冲突错误（Unique Constraint Violation），请在迁移完成后连接到 PostgreSQL 执行以下 SQL 重置序列：

-- 将 your_table_name 与 id 替换为实际的表名和主键字段名
SELECT setval(
  pg_get_serial_sequence('your_table_name', 'id'), 
  COALESCE((SELECT MAX(id) FROM your_table_name), 1)
);

📄 LicenseMIT License

MIT License