sql_dump_load_tool:基于 Python 的数据库数据迁移工具项目

可用于数据库间的数据迁移、备份与恢复。支持PostgreSQL/OpenGauss,异步批量读写千万级数据,兼容UUID、Numpy数组等特殊类型,自动初始化表结构,中文日志输出,操作便捷高效。【此简介由AI生成】

Branch1Tags0

SQL Dump & Load Tool 数据迁移工具使用文档

一、工具概述

✅ 核心功能

一款异步高性能的数据库全量数据导出(Dump)与导入(Load)工具,支持将指定数据库的全量业务数据导出为标准JSON文件,也可将JSON文件数据无损回灌入目标数据库,实现数据库间的数据迁移、备份与恢复。

✅ 核心特性

✅ 支持 PostgreSQL / OpenGauss 两大主流数据库,无缝兼容切换 ✅ 异步批量读写,采用1024条分批策略,支持千万级数据高效迁移,无内存溢出风险 ✅ 完美兼容UUID、Numpy数组(ndarray)、datetime/date、np.int/np.float等特殊数据类型,序列化/反序列化无损转换 ✅ 导出数据自动按表分片存储,导入时主键冲突自动跳过,全程不中断 ✅ 自动校验并初始化数据库表结构,无需手动建表,开箱即用 ✅ 全中文日志输出,执行状态、数据量、异常信息一目了然 ✅ 过滤SQLAlchemy内部属性,导出JSON为纯业务数据,格式规范可直接解析

二、支持的数据库表清单

工具默认对以下业务表进行全量导出/导入,表加载顺序已做合理性适配,无关联外键导入异常:

TeamEntity、TeamMessageEntity、RoleEntity、ActionEntity、RoleActionEntity
UserEntity、UserMessageEntity、TeamUserEntity、UserRoleEntity、KnowledgeBaseEntity
DocumentTypeEntity、DocumentEntity、ChunkEntity、ImageEntity、DataSetEntity
DataSetDocEntity、QAEntity、TestingEntity、TestCaseEntity、TaskEntity
TaskReportEntity、TaskQueueEntity

三、环境依赖

✅ 基础Python环境

Python 3.8+(需支持异步语法 async/await 及现代标准库)

✅ 第三方依赖包

需提前安装以下依赖,可直接执行下方命令一键安装:

pip install numpy sqlalchemy asyncpg python-dotenv

✅ 项目内部依赖

确保项目目录下存在以下核心模块(与本脚本同级):

  • config.py:包含 DatabaseConfig 配置类、DatabaseType 枚举类
  • database.py:包含 DataBase 数据库核心类、上述所有ORM实体类(*Entity)

四、命令行参数说明

工具基于argparse实现全参数化运行,所有参数均为必填项,无默认值,参数通过--参数名 值的形式传入,完整参数列表如下:

参数名 类型 取值范围 必选 说明
--action str dump / load ✅ 执行动作:
dump = 导出数据库数据到本地
load = 从本地导入数据到数据库
--db-type str postgresql / opengauss ✅ 数据库类型,与DatabaseType枚举值一致
--db-host str 合法IP/域名 ✅ 数据库服务端地址(如:127.0.0.1、192.168.1.100)
--db-port int 合法端口号 ✅ 数据库端口(PostgreSQL默认5432,OpenGauss默认5432)
--db-user str 数据库用户名 ✅ 具备增/删/查/建表权限的数据库账号
--db-password str 数据库密码 ✅ 对应账号的登录密码
--db-name str 数据库实例名 ✅ 要操作的目标数据库名称

五、核心操作命令

✅ 操作1:数据库数据导出(Dump)

将目标数据库的全量表数据导出到本地 ./tmp 目录,自动生成按表+分片命名的JSON文件。

命令示例(PostgreSQL)

python main.py \
--action dump \
--db-type postgresql \
--db-host 127.0.0.1 \
--db-port 5432 \
--db-user postgres \
--db-password 123456 \
--db-name my_database

命令示例(OpenGauss)

python main.py \
--action dump \
--db-type opengauss \
--db-host 192.168.1.200 \
--db-port 5432 \
--db-user gaussdb \
--db-password Gauss@123 \
--db-name gauss_database

导出结果说明

  • 执行前会自动清空并重建 ./tmp 目录,避免历史数据干扰
  • 每个表的数据按1024条分片,文件命名格式:表名_分片序号.json(如:user_0.json、team_1.json)
  • 所有JSON文件采用UTF-8编码,格式化缩进4空格,支持直接打开查看/编辑

✅ 操作2:数据库数据导入(Load)

将本地 ./tmp 目录下的JSON分片文件,批量导入到目标数据库,需保证导出的JSON文件已存在于该目录。

命令示例

python main.py \
--action load \
--db-type postgresql \
--db-host 10.0.0.5 \
--db-port 5432 \
--db-user postgres \
--db-password 654321 \
--db-name target_database

导入核心特性

✅ 自动初始化数据库引擎,校验并创建缺失的表结构,无需手动建表 ✅ 按表顺序批量插入,单分片导入失败自动跳过,继续下一分片,不终止整体流程 ✅ 特殊数据类型自动反向转换(UUID字符串→UUID对象、列表→ndarray、时间字符串→datetime/date) ✅ 实时输出导入进度,包含「表名、分片序号、单批次导入条数、累计导入条数」

六、核心工具函数说明

✅ orm_obj_to_dict(orm_obj) - ORM对象序列化核心函数

作用:将SQLAlchemy的ORM实体对象,转换为JSON可序列化的Python原生字典,是导出功能的核心。 ✅ 核心能力:

  1. Numpy数组(ndarray)→ 原生列表,空数组自动转为空列表
  2. Numpy数值(np.int/np.float)→ Python原生int/float
  3. UUID对象 → 字符串格式(如:f47ac10b-58cc-4372-a567-0e02b2c3d479)
  4. datetime → 标准字符串(%Y-%m-%d %H:%M:%S)
  5. date → 标准字符串(%Y-%m-%d)
  6. 过滤SQLAlchemy内部属性(如_sa_instance_state),仅保留业务字段
  7. 空值/空数据自动兜底,永不抛出序列化异常

✅ convert_special_type_for_orm(data) - JSON数据反序列化核心函数

作用:将JSON读取的原生字典,转换为ORM实体可接收的格式,与orm_obj_to_dict严格反向对应,是导入功能的核心。 ✅ 核心能力:

  1. 合法UUID字符串 → Python UUID对象
  2. 列表 → Numpy ndarray数组
  3. 时间字符串 → datetime/date对象(自动匹配两种时间格式)
  4. 空值直接保留,非特殊类型原样返回

✅ is_valid_uuid(uuid_str) - 辅助校验函数

作用:校验字符串是否为合法的UUID格式,为反序列化提供支撑,返回布尔值。

七、注意事项 ⚠️

✅ 权限要求

  1. 执行工具的数据库账号,必须具备CONNECT、SELECT、INSERT、CREATE TABLE权限
  2. 本地运行脚本的用户,需具备当前目录的读写权限(用于创建/修改./tmp目录)

✅ 数据一致性

  1. 导出时:建议暂停业务写入,避免导出过程中数据变更导致的不一致;若无法暂停,导出数据为「执行时刻的快照」
  2. 导入时:目标数据库若已存在同名数据(主键冲突),工具会自动跳过该批次,不会覆盖原有数据
  3. 导入仅新增数据,不会删除目标数据库的原有数据

✅ 特殊类型兼容

  1. 所有Numpy数组导出后为原生列表,导入时自动还原为ndarray,数据维度/值完全无损
  2. 时间类型严格遵循「导出格式=导入格式」,跨时区部署时需保证数据库时区一致
  3. UUID类型全程无转换丢失,保证主键唯一性

✅ 性能优化建议

  1. 批量大小默认1024条,可根据服务器内存调整(修改代码中batch_size变量)
  2. 千万级数据迁移时,建议在服务器本地执行,避免网络传输瓶颈
  3. 导入/导出过程中,关闭数据库其他高负载操作,提升迁移速度

✅ 异常排查

  1. 常见错误:「数据库连接失败」→ 检查db-host/db-port/db-user/db-password是否正确,网络是否互通
  2. 常见错误:「表不存在」→ 检查database.py中是否包含对应ORM实体类,或账号无建表权限
  3. 常见错误:「JSON文件读取失败」→ 检查./tmp目录是否存在、文件是否损坏、编码是否为UTF-8

八、整体工作流程

✅ 导出流程(dump)

  1. 解析命令行参数 → 生成数据库配置对象
  2. 初始化数据库引擎,校验表结构
  3. 清空本地./tmp目录,重建目录
  4. 遍历所有业务表,按1024条分批查询数据
  5. ORM对象序列化为原生字典 → 写入JSON分片文件
  6. 所有表导出完成,输出最终结果

✅ 导入流程(load)

  1. 解析命令行参数 → 生成数据库配置对象
  2. 初始化数据库引擎,自动创建缺失的表结构
  3. 遍历所有业务表,按分片顺序读取JSON文件
  4. JSON数据反序列化为ORM实体对象 → 批量插入数据库
  5. 实时输出导入进度,异常分片自动跳过
  6. 所有表导入完成,输出各表累计导入条数

工具维护说明:本工具支持灵活扩展,如需新增导出/导入表,仅需在table_list列表中添加对应的ORM实体类即可,无需修改其他逻辑。

Introduction

可用于数据库间的数据迁移、备份与恢复。支持PostgreSQL/OpenGauss,异步批量读写千万级数据,兼容UUID、Numpy数组等特殊类型,自动初始化表结构,中文日志输出,操作便捷高效。【此简介由AI生成】

Customize your domain