DolphinDB 高可用 MVCC 表使用指南

要使用高可用 MVCC 表，要求在集群中配置至少三个数据节点或计算节点。

相关的配置项主要的有：

• mvccTableRaftGroups：配置 Raft 组。格式为："groupId:node_name1:node_name2:node_name3"，其中 groupId 表示 Raft 组号，为大于等于 2 的整数，node_name 为数据节点或计算节点的节点名字，须配置至少 3 个，中间用冒号分隔。系统支持配置多组，用逗号分隔。建议每组的节点分别位于不同的服务器上，以防止一台服务器宕机，组内节点都不可用。

• mvccTableHADir：高可用 MVCC 表的持久化存储目录。默认目录为：<HomeDir>/log/mvccHA。在集群模式中，需要保证同一机器上的数据节点或计算节点配置了不同的 mvccTableHADir。

• mvccTableCheckpointInterval：用于控制定期做 Checkpoint 的时间间隔。单位为秒。默认值为300秒。

用户需要在集群 cluster.cfg 配置文件中配置上述参数。以下例子配置了2个 Raft 组，组2包含3个数据节点，分别为 datanode2、datanode3、datanode4。组3包含3个数据节点，分别为 datanode5、datanode6、datanode7。

mvccTableRaftGroups=2:datanode2:datanode3:datanode4,3:datanode5:datanode6:datanode7
mvccTableCheckpointInterval=300

可使用 getHaMvccRaftGroups 函数以获取用户在集群配置的 Raft 组。从而确定当前节点的 Raft 组 ID，供后续建表操作使用。

此函数只能获取当前节点上配置的 Raft 组。例如在上述例子中配置的 datanode2 上运行 getHaMvccRaftGroups() ，结果如下：

在集群中配置 Raft 组后，每个 Raft 组会自动选举产生一个 Leader，其余节点作为 Follower。Leader 负责接收并处理客户端请求。当 Leader 发生故障时，系统会自动发起重新选举，选出新的 Leader，从而保证服务的高可用性。

可以通过调用 getHaMvccLeader 函数获取指定 Raft 组当前的 Leader 节点。函数语法如下：

getHaMvccLeader(groupId)

其中参数 groupId 是 Raft 组的编号。

需要注意的是，只能在该组配置的数据节点上运行该函数。例如要获取上述例子配置的 Raft 组2的 Leader，可以在 datanode2、datanode3、datanode4上 运行下列代码：

getHaMvccLeader(2)

若要在非该组的节点上获取组2的 Leader，需要先获取配置了该组的任意节点，然后使用 rpc 函数到该节点获取 Leader。例子如下：

t=exec top 1 id,node from pnodeRun(getHaMvccRaftGroups) where id =2
leader=rpc(t.node[0],getHaMvccLeader,t.id[0])

使用函数 haMvccTable 创建创建高可用 MVCC 表。语法见 haMvccTable。

一个 Raft 组可以包含多个高可用 MVCC 表。这里要注意以下几点：

• 高可用 MVCC 表在日志中持久化了表结构信息，重启后不需要重新建表。

• 只能在 Leader 上执行创建高可用 MVCC 表的函数。

下面的例子在 Raft 组2上创建了一个高可用 Mvcc 表 hmt，指定了每一列的默认值，且允许 name 和 value 列包含空值。

schemaTb = table(10:0, `name`id`value, [STRING,INT,DOUBLE])
haMvccTable(2:2, schemaTb, `hmt, 2,(`str,2,3),[true,false,true])

可以用 getHaMvccTableInfo 函数获取属于该 groupId 的所有高可用 MVCC 表的元信息。语法和介绍见 getHaMvccTableInfo

注：如果要查询 groupId=2 的高可用 MVCC 表的元信息，则必须在 raftGroup 为2的 Raft 成员节点上执行该运维函数。

例如：首先在 Raft 组2的 leader 节点 上创建高可用 MVCC 表

schemaTb = table(10:0, `name`id`value, [STRING,INT,DOUBLE])
haMvccTable(10:0, schemaTb, `t1, 2)

在 Raft 组2的任意节点上执行 getHaMvccTableInfo(2) ，可以得到 t1 表的元数据信息如下：

在读取高可用 MVCC 表数据前，需要先获取表的句柄。可以在 Raft 组内任意节点上执行 loadHaMvccTable 获取指定的句柄，然后使用 select 语句查询表数据。例如在 datanode2 上获取2.5中 hmt 表的数据：

t=loadHaMvccTable(`hmt)
select * from t

得到结果：

使用 dropHaMvccTable 删除指定高可用 MVCC 表。语法见 dropHaMvccTable。

可以通过以下方法往高可用 MVCC 表中插入数据：

1. SQL insert 语句

   //往指定列插入数据，其他列为空
   insert into trades(sym,date) values(`S,2000.12.31)
   //往所有列插入数据
   insert into trades values(`S`IBM,[2000.12.31,2000.12.30],[10.0,20.0],[10.0,20.0],[10.0,20.0],[10.0,20.0],[10.0,20.0],[10.0,20.0],[10,20],[10,20],[10,20],[10,20],[10,20],[10,20])

2. append! 函数

   如果使用 append! 函数往表中插入数据，新数据必须是表。例如：

   tmp=table(`S`IBM as col1,[2000.12.31,2000.12.30] as col2,[10.0,20.0] as col3,[10.0,20.0] as col4,[10.0,20.0] as col5,[10.0,20.0] as col6,[10.0,20.0] as col7,[10.0,20.0] as col8,[10,20] as col9,[10,20] as col10,[10,20] as col11,[10,20] as col12,[10,20] as col13,[10,20] as col14)
   trades.append!(tmp)

3. tableInsert 函数

   tableInsert 函数会返回插入的行数。

   如果使用 tableInsert 函数往表中插入数据，新数据必须是表。

   tmp=table(`S`IBM as col1,[2000.12.31,2000.12.30] as col2,[10.0,20.0] as col3,[10.0,20.0] as col4,[10.0,20.0] as col5,[10.0,20.0] as col6,[10.0,20.0] as col7,[10.0,20.0] as col8,[10,20] as col9,[10,20] as col10,[10,20] as col11,[10,20] as col12,[10,20] as col13,[10,20] as col14)
   trades.tableInsert(tmp)
   2

4. 写入高可用

   Java、C++ 和 Python API 已支持对该表的高可用写入：在 connect 函数中通过 highAvailabilitySites 参数指定多个候选节点（ host:port 格式的数组）。当 Leader 切换时，API 会自动捕获异常并从中获取新 Leader 信息，切换至新 Leader 继续写入，从而确保节点故障时写入任务不中断。Python API代码举例如下：

   host = "127.0.0.1"
   port = 26903
   sites = [host+":26903",host+":26904", host+":26905"]
   s.connect(host=host, port=port, userid="admin", password="123456",
                         highAvailability=True, highAvailabilitySites=sites, reconnect=True)

可以通过以下方法为高可用 MVCC 表更新列：

1. SQL update 语句

   update trades set qty1=qty1+10;
   update trades set qty1=qty1+10 where sym=`IBM;

2. update! 函数

   trades.update!(`qty1, <qty1+10>);
   trades.update!(`qty1, <qty1+10>, <sym=`IBM>);

3. sqlUpdate 函数

   sqlUpdate(trades,<qty1+10 as qty1>).eval()

4. 赋值语句

   trades[`qty1] = <qty1+10>;
   trades[`qty1, <sym=`IBM>] = <qty1+10>;

可以通过以下方法为高可用 MVCC 表删除行：

1. SQL delete 语句

   delete from trades where qty3<20;

2. sqlDelete 函数

   sqlDelete(trades,< qty3<30 >).eval()

可以通过以下方法为高可用 MVCC 表增加列：

1. SQL update 语句

   update trades set logPrice1=log(price1), newQty1=double(qty1);

2. update! 函数

   trades.update!(`logPrice1`newQty1, <[log(price1), double(qty1)]>);

3. 赋值语句

   trades[`logPrice1`newQty1] = <[log(price1), double(qty1)]>;

1. 通过 drop! 函数删除列：

   trades.drop!("qty1");

2. 通过 dropColumns! 函数删除列：

   dropColumns!(trades,`qty3)

通过 rename! 函数重命名列：

trades.rename!("qty2", "qty2New");

通过 replaceColumn! 函数修改列

replaceColumn!(trades,`qty4,trades[`qty5])

通过 setHaMvccColumnNullability 设置高可用 MVCC 表的列是否允许为空。语法和用法见 setHaMvccColumnNullability。

通过 setHaMvccColumnDefaultValue 设置高可用 MVCC 表的列的默认值。语法和用法见 setHaMvccColumnDefaultValue。

DolphinDB 提供了两个运维函数用于管理高可用 MVCC 表的 Checkpoint：

1. checkpointHaMvcc

   checkpointHaMvcc 函数可以用来手动强制执行组内节点的 Checkpoint 例如在 Raft 组2中任意节点执行：

   checkpointHaMvcc(2)

2. isCheckpointingHaMvcc

   isCheckpointingHaMvcc 可以实时监控指定的 Raft 组是否正在执行 Checkpoint 操作。这为系统的健康检查和运维诊断提供了便利，有助于了解系统后台任务的运行状态。例如在 Raft 组2中任意节点执行：

   isCheckpointingHaMvcc(2)

   注：

   上述两个函数只在当前节点生效，如需在 Raft 组内的其他节点上执行，请先建立与目标节点的连接。