Plugin

介绍

Plugin 仓主要承载 openGauss 的插件扩展能力，其中 dolphin 插件用于在 openGauss-server 基础上补充 B 库语法、函数、数据类型、类型转换等能力。

参与贡献

1. 按照社区特性设计模板（ https://gitcode.com/opengauss/community/tree/master/design/template ）撰写特性设计说明书，并在plugin sig例会上评审通过
2. 代码编写/自测，提交代码review，修改检视意见
3. 如果需求涉及资料修改，同步提交资料PR（ https://gitcode.com/opengauss/docs ），dolphin相关的语法文档入口为 https://gitcode.com/opengauss/docs/tree/master/docs/zh/extension_reference ，对应官网页面： https://docs.opengauss.org/zh/docs/latest/docs/ExtensionReference/dolphin-Extension.html
4. 按照社区check-in模板（ https://gitcode.com/opengauss/community/tree/master/check-in/template ）撰写checkin说明书，并在plugin sig例会上评审通过
5. 代码合入
6. 按照社区QA测试报告模板（ https://gitcode.com/opengauss/QA/tree/master/Test_Delivery_Templates ）撰写openGauss XX版本XX特性测试报告模板.md，并在 QA sig例会上评审通过（QA sig例会请通过订阅QA SIG邮件列表获知信息： https://mailweb.opengauss.org/postorius/lists/qa.opengauss.org/ ）

dolphin插件开发须知

1. 插件开发指南： https://opengauss.org/zh/blogs/ganyang/SQL引擎插件开发指导.html
2. 修改如涉及文档，需要同步在docs仓提交文档修改，插件相关文档入口： https://gitcode.com/opengauss/docs/tree/master/docs/zh/extension_reference 。注意添加SQL语法时，需要增加必要的示例。
3. 新增/修改的代码需要使用宏 DOLPHIN 进行控制，方便后续回合openGauss-server仓代码时，区分哪些是插件修改的代码，哪些是内核修改的代码。修改的代码通过宏的IF/ELSE分支保留原始代码。主要控制 .h/.cpp 文件， .y 文件不太好使用宏控制，可以不处理。
4. 代码中涉及dolphin.b_compatibility_mode判断的地方，统一使用宏ENABLE_B_CMPT_MODE控制。
5. 涉及插件升级/回滚脚本修改的，应本地自验插件的升级/回滚流程，确保脚本正确，简单验证方式如下。 2.0，3.0是dolphin插件的版本，当前最新版本为 3.0，后续版本号升级的话，就分别改为 3.0，4.0，以此类推

alter system set upgrade_mode to 2;
select pg_sleep(2);
begin;
set isinplaceupgrade to on;
set dolphin.b_compatibility_mode = off;
alter extension dolphin update to '2.0';
alter extension dolphin update to '3.0';
reset dolphin.b_compatibility_mode;
abort;

alter system set upgrade_mode to 0;

check用例编写规范

1. check用例默认使用的数据库为contrib_regression数据库，B兼容类型。编写用例时无需自己手动创建B类型数据库。
2. 建议通过schema的方式隔离不同用例间的结果影响。可参考现有用例的写法。
3. 单个用例执行时间不宜太长，建议不超过10s，超过的应当考虑优化用例或进行拆分。
4. 非必要不新增测试组，一个测试组可允许5~10个用例一起并行执行。
5. 对于SELECT语句强烈建议增加order by子句，保证SELECT语句查询结果稳定。

dolphin 插件 check 用例执行

1. 拉取代码仓

   分别拉取 openGauss-server仓 和 Plugin仓 代码。

2. 准备 dolphin 插件目录

   将 Plugin 仓中 contrib/dolphin 目录复制或软链接到 openGauss-server 仓的 contrib 目录下，最终目录结构应为：

   openGauss-server/contrib/dolphin
   

3. 编译 openGauss-server

   在 openGauss-server 仓根目录下执行 make 编译项目代码。

   注：dolphin check 用例依赖 make 编译产物，需使用 make 完成编译。

4. 执行 dolphin check 用例

   dolphin 用例按照 schedule 文件分组执行，主要对应以下两个文件：

   contrib/dolphin/parallel_schedule_dolphinA
   contrib/dolphin/parallel_schedule_dolphinB
   

   先确认目标用例位于哪个 schedule 文件中。若用例在 parallel_schedule_dolphinA 中，则进入 contrib/dolphin 目录后执行：

   cd contrib/dolphin
   make check p=38000 PART=A
   

   若用例在 parallel_schedule_dolphinB 中，则执行：

   cd contrib/dolphin
   make check p=38000 PART=B
   

   其中，p 为数据库监听端口，可根据本地环境调整；PART 用于指定执行 A 组或 B 组用例。

5. 执行单个用例

   若只需执行单个用例，建议先备份对应的 schedule 文件。例如用例属于 A 组：

   cp parallel_schedule_dolphinA parallel_schedule_dolphinA.bak
   

   然后新建或修改 parallel_schedule_dolphinA，仅保留需要执行的用例，格式可参考原文件中的写法，例如：

   test: your_test_name
   

   修改完成后执行：

   make check p=38000 PART=A
   

   执行结束后，可根据需要恢复原 schedule 文件。