把SQLite单文件数据库直接搬到中兴通讯GoldenDB分布式数据库，真的只是改一个连接串吗？答案显然是否定的。SQLite的数据存储和事务处理方式与GoldenDB存在根本性差异，如果忽视这些差异直接迁移，很容易出现类型报错、导入缓慢甚至数据不一致。本文以一个订单库迁移项目为主线，拆解从架构评估到数据校验的完整过程。
一、SQLite与GoldenDB的关键差异
SQLite是一个嵌入式数据库，没有独立的服务进程，所有表和索引都保存在一个以.db结尾的文件中。它的写事务采用库级锁，同一时间只允许一个写操作，读操作可以在不同版本上并发进行，但写入吞吐量天然受限。这种设计适合移动端、桌面工具和小型后端服务，一旦业务规模上来，写并发就会成为瓶颈。
GoldenDB则完全不同。它是中兴通讯面向金融级场景的分布式数据库，通常包含计算节点、数据节点和管理节点，数据按照分片规则分布在多个数据节点上。GoldenDB兼容MySQL协议和常用SQL语法，支持分布式事务与MVCC，对DECIMAL、DATETIME、TINYINT等类型有严格校验。两者在类型系统上的差异会直接影响迁移脚本的编写。
下面用同一张订单表对比两者的建表语法。SQLite允许动态类型，INTEGER PRIMARY KEY AUTOINCREMENT可以自动生成自增主键，日期可以直接存为TEXT，布尔值用INTEGER表示。GoldenDB虽然也兼容很多MySQL语法，但对列类型、长度和主键定义要求更明确。
-- SQLite 建表
CREATE TABLE orders (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
amount REAL,
created_at TEXT DEFAULT CURRENT_TIMESTAMP,
is_active INTEGER DEFAULT 1
);
-- GoldenDB 建表
CREATE TABLE orders (
id BIGINT NOT NULL,
name VARCHAR(128) NOT NULL,
amount DECIMAL(18,2),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
is_active TINYINT DEFAULT 1,
PRIMARY KEY (id)
) DISTRIBUTED BY HASH (id);可以看到，SQLite里的REAL在GoldenDB中最好映射为DECIMAL，避免浮点精度问题；TEXT日期要改为DATETIME；布尔值用TINYINT更规范。更重要的是，GoldenDB分布式表需要指定DISTRIBUTED BY HASH，这个分片键选择会直接影响后续写入和查询性能。
二、迁移实战：用Python把数据写入GoldenDB
迁移方案通常有三种：导出SQL文件后手工执行、生成CSV后使用批量导入工具、编写脚本通过驱动逐批写入。对于几万到几十万行数据，第三种方式最灵活，因为可以在脚本里完成类型清洗、字段转换和错误捕获。GoldenDB兼容MySQL协议，因此可以直接使用pymysql驱动连接。
下面的脚本从SQLite的orders表读取数据，每次取1000行，转换后将数据批量插入GoldenDB。这里没有一次性读取全部数据，是为了避免内存占用过高，也方便在中断后从某个批次继续。
import sqlite3
import pymysql
from datetime import datetime
sqlite_conn = sqlite3.connect('local.db')
sqlite_cur = sqlite_conn.cursor()
goldendb_conn = pymysql.connect(
host='127.0.0.1',
port=3306,
user='gdba',
password='your_password',
database='target_db',
charset='utf8mb4'
)
goldendb_cur = goldendb_conn.cursor()
sqlite_cur.execute('SELECT id, name, amount, created_at, is_active FROM orders')
rows = sqlite_cur.fetchmany(1000)
while rows:
values = []
for row in rows:
id_val, name, amount, created_at, is_active = row
# SQLite 日期可能存成字符串，需要转成 datetime 对象
if isinstance(created_at, str):
created_at = datetime.strptime(created_at, '%Y-%m-%d %H:%M:%S')
# 布尔值统一转成 0 或 1
if isinstance(is_active, int):
is_active = 1 if is_active else 0
values.append((id_val, name, amount, created_at, is_active))
insert_sql = 'INSERT INTO orders (id, name, amount, created_at, is_active) VALUES (%s, %s, %s, %s, %s)'
goldendb_cur.executemany(insert_sql, values)
goldendb_conn.commit()
rows = sqlite_cur.fetchmany(1000)
sqlite_cur.close()
goldendb_cur.close()
sqlite_conn.close()
goldendb_conn.close()这段代码演示了两种最常见的类型转换：日期字符串转datetime对象、布尔整数统一为0或1。实际项目中还可能出现SQLite里的NULL、空字符串、时区偏移等脏数据，这些都需要在执行插入前补一层校验。比如金额字段在SQLite里可能因为弱类型被写成'abc'，如果直接写入GoldenDB的DECIMAL列会直接报错。建议在values.append之前加入try捕获和格式修正。
批量提交的另一个关键是executemany配合commit的频率。如果每一行都提交一次，网络往返和事务开销会非常惊人；如果整个迁移过程只有一个大事务，一旦中途失败，所有已写入的数据都可能回滚，而且GoldenDB端的事务日志压力也会很大。在订单迁移中，每1000行提交一次是比较稳妥的选择，既能保证性能，又能把失败范围控制在一个小批次内。
三、分片键设计与性能调优
GoldenDB的分布式表必须指定分片键。分片键的选择不能只看建表方便，还要结合业务查询模式。如果订单表最常见的查询是WHERE user_id = ?，那么把分片键设为user_id可以让查询直接路由到单个数据节点，避免跨节点扫描。如果主键id是自增序列，把它作为分片键虽然分散均匀，但很多按用户维度的查询会退化为全分片扫描。
下面是一张更适合按用户维度查询的订单表结构。主键采用(id, user_id)联合主键，分片键选择user_id，这样插入和查询都能被正确路由。
CREATE TABLE orders (
id BIGINT NOT NULL,
user_id BIGINT NOT NULL,
name VARCHAR(128),
amount DECIMAL(18,2),
created_at DATETIME,
PRIMARY KEY (id, user_id)
) DISTRIBUTED BY HASH (user_id);注意，如果业务上依赖SQLite的自增id作为全局唯一标识，迁移到分布式环境后，需要重新设计ID生成策略。GoldenDB本身不保证跨分片的自增连续递增，直接使用AUTO_INCREMENT可能会出现重复或跳号。通常做法是使用雪花算法、UUID或独立的序列表来生成全局唯一ID，再显式写入id字段。
导入性能方面，如果目标表已经建了大量二级索引，批量写入速度会明显下降，因为每个批次都要维护索引结构。对于一次性迁移，可以先创建表结构，暂时不建二级索引，等数据全部导入完成后再统一创建索引。这样能大幅缩短导入耗时。GoldenDB支持在线创建索引，但具体语法需要参照对应版本的DDL规范，建议在测试环境先验证。
四、一致性校验与常见避坑点
数据迁移完成后，必须做一致性校验，不能只凭导入脚本没报错就认为成功。最简单的方式是分别统计SQLite和GoldenDB中的行数，以及关键列的聚合值。比如总金额SUM(amount)、最大创建时间MAX(created_at)，这些聚合结果如果在两库一致，基本可以说明数值字段没有丢失或截断。
更严格的做法是对每一行计算校验和。下面这段Python脚本会遍历SQLite和GoldenDB的订单表，按id排序后对整行内容做MD5，再比较两边的校验和是否一致。注意两边排序规则要保持相同，否则结果没有可比性。
import hashlib
def sqlite_checksum(conn):
cur = conn.cursor()
hasher = hashlib.md5()
for row in cur.execute('SELECT id, name, amount, created_at, is_active FROM orders ORDER BY id'):
hasher.update(str(row).encode('utf-8'))
return hasher.hexdigest()
def goldendb_checksum(conn):
cur = conn.cursor()
hasher = hashlib.md5()
cur.execute('SELECT id, name, amount, created_at, is_active FROM orders ORDER BY id')
for row in cur.fetchall():
hasher.update(str(row).encode('utf-8'))
return hasher.hexdigest()在真实迁移中还有几个高频坑点需要提前处理。第一个是日期格式：SQLite里CURRENT_TIMESTAMP默认返回UTC时间，而GoldenDB的DATETIME如果使用服务器本地时区，可能产生几个小时的偏差。迁移前需要确认两边的时区设置，并在脚本中统一转换为同一时区。第二个是布尔值：SQLite没有原生布尔类型，通常用INTEGER表示，但可能存在-1或2这样的异常值，需要在转换时只接受0和1，其余情况单独记录。
第三个是自增序列重置。如果业务要求迁移后继续使用原来的自增ID，导入完成后需要把GoldenDB的序列起始值设置为MAX(id) + 1。这通常通过修改自增列当前值来实现，具体语法与MySQL类似。第四个是字符集问题，SQLite默认使用UTF-8，GoldenDB连接也需要明确指定utf8mb4，否则中文或emoji内容可能出现乱码。最后，建议先在GoldenDB测试实例上完整跑一遍迁移脚本，记录耗时和失败行，再对生产库执行正式迁移。
总的来说，SQLite到GoldenDB的迁移不是简单的数据搬运，而是从单机思维向分布式思维的转变。类型映射、分片键设计、批量提交策略和一致性校验四件事做到位，才能让项目在新数据库上稳定运行。