富客户端

富客户端功能将 ODP 的整体路由转发能力融入到 OceanBase Connector/J 驱动中，由此业务端不再需要单独部署和管理 ODP 节点。 富客户端功能适用于业务应用机器和数据库机器之间网络互通，且业务应用所在机器资源充足，客户没有或者不想使用负载均衡设备，或者客户希望得到更低访问时延的场景。

富客户端访问原理

使用富客户端访问 OceanBase 数据库的原理图如下：

OceanBase Connector/J 的富客户端组件如下：

• JDBC-ObProxySocket：富客户端能力的 JDBC 驱动，实现多个 JNI 接口，并拉起 obproxy 后台工作线程进行与后端数据库的交互操作。
• OBProxy_so：承载 ODP 整体能力的动态库，提供接口在后台拉起工作线程，并处理转发所有数据库请求。

富客户端支持使用 ODP 系统账号登录并调节相关 ODP 参数，但只能在本机通过指定域名套接字的形式登录。 富客户端 ODP 动态库拥有 ODP 的所有日志能力，默认在业务机器的当前目录创建 .obproxy 隐藏目录，内部包含 log 日志目录，ODP 的运行日志会记录在该目录下的日志文件中。 富客户端产生的 ODP 动态库的日志可以执行自动清理，触发清理的磁盘使用上限由 log_dir_size_threshold 参数控制，在业务重启后日志清理会继续执行，不会受业务重启的影响。

开启富客户端功能

1. 下载对应版本的 OceanBase Connector/J 安装包（jar 包）和 ODP 安装包（rpm 包）。

2. 安装 ODP。Linux 环境下安装命令如下：

   rpm -ivh obproxy-x.x.x-x.x.x.rpm；
   

3. 在 /u01/obproxy/lib/libobproxy_so.so 目录下做动态库软链接，如果该路径不存在，则通过 -Djava.library.path=xxx 指定的路径查找。

4. 通过 OceanBase Connector/J 的 URL 连接设置 obProxySocket 属性开启富客户端功能。启动富客户端时可以指定日志级别，也支持在运行时动态调整 ODP 打印日志的级别。示例如下：

   #通过 RSLIST 启动富客户端：
   &obProxySocket={\"proxy_config\":\"rootservice_cluster_name=***,rootservice_list=10.XXX.XXX.XXX:2727,proxy_mem_limited=1G,work_thread_num=8,syslog_level=INFO,enable_client_ip_checkout=false,check_tenant_locality_change=false,enable_async_pull_location_cache=false,enable_compression_protocol=true,enable_async_log=true,syslog_level=INFO\"}
   
   #通过 OCP_CONFIG_URL 启动富客户端：
   &obProxySocket={\"proxy_config\":\"rootservice_cluster_name=***,obproxy_config_server_url=***,proxy_mem_limited=1G,work_thread_num=8,syslog_level=INFO,enable_client_ip_checkout=false,check_tenant_locality_change=false,enable_async_pull_location_cache=false,enable_compression_protocol=true,enable_async_log=true,syslog_level=INFO\"}
   

   obProxySocket 的内容为 json 格式，目前只支持一对 key-value，其中 key为 proxy_config。value字段为 ODP 的配置项，详细信息请参见 ODP 配置参数。

   如果要使用富客户端功能，必须设置集群信息，方式如下：

   • 方式一：设置 obproxy_config_server_url，值为 OCP 的访问地址。
   • 方式二：设置 RsList，配置项包括 rootservice_list 和 rootservice_cluster_name。

   针对富客户端功能推荐一些调优配置项如下表所示。

   配置项名称	默认值	推荐值	说明
   automatic_match_work_thread	true	false	如果为 true，富客户端线程数为min(work_thread_num, CPU 核数)，其中 work_thread_num 为配置项。
   work_thread_num	128	8	线程数，实际结果受到automatic_match_work_thread 影响。
   proxy_mem_limited	2G	16G	当富客户端使用的内存超 proxy_mem_limited 时，富客户端线程会自动退出。
   enable_strict_kernel_release	true	false	是否检查内核版本，检查不通过会导致启动失败。
   log_dir_size_threshold	64G	1G	日志文件的磁盘使用上限，超过该上限会自动清理日志。
   syslog_level	INFO	INFO/ERROR	日志打印级别，生产建议设置为 INFO，如果不需要打印日志可以改为 ERROR 级别。

5. 开启富客户端后，使用 OceanBase Connector/J 接口与数据库进行正常交互。

使用示例

本文以 OceanBase Connector/J V2.3.0 和 ODP V3.3.0 的安装环境为例，展示富客户端的功能。

1. 创建测试用例 TestOBClientVC.java。

   import java.io.*;
   import java.sql.*;
   import static java.lang.Thread.sleep;
   
   public class TestOBClientVC {
       public static int useVC = 0;
       public static final String obproxyConfig = "&obProxySocket={\"app_name\":\"mytest\",\"proxy_config\":\"rootservice_cluster_name=***,rootservice_list=10.XXX.XXX.XXX:2727,proxy_mem_limited=2G,work_thread_num=8,syslog_level=DEBUG\"}";
   
       public static Connection getObConnection() throws Exception {
          //设置连接信息
           final String DRIVER_NAME = "com.alipay.oceanbase.jdbc.Driver";
           final String URL = "jdbc:oceanbase://10.XXX.XXX.XXX:20211/test?useSSL=false&useServerPrepStmts=true&log=true";
           final String USER_NAME = "root@***";
           final String PASSWORD = "";
   
           //加载mysql的驱动类
           Class.forName(DRIVER_NAME);
           //获取数据库连接
           if (useVC != 0) {
               return (Connection) DriverManager.getConnection(URL + obproxyConfig, USER_NAME, PASSWORD); //clientVC
           } else {
               return (Connection) DriverManager.getConnection(URL, USER_NAME, PASSWORD); //tcp socket
           }
       }
   
        public static void test_text_protocol() {
           Connection conn = null;
           try {
               conn = getObConnection();
               System.out.println("get connection succ");
               ResultSet rs = conn.createStatement().executeQuery("select 'hello obproxy!' from dual");
   
               if (rs.next()) {
                 System.out.println("text:" + rs.getString(1));
               }
            } catch (Exception e) {
               e.printStackTrace();
           }
       }
   
       public static void test_binary_protocol() {
          Connection conn = null;
          try {
              conn = getObConnection();
              PreparedStatement pstmt = conn.prepareStatement("select ? from dual");
              pstmt.setString(1, "hello obproxy!");
              pstmt.execute();
              ResultSet rs = pstmt.getResultSet();
   
              if (rs.next()) {
                System.out.println("text:" + rs.getString(1));
              }
          } catch (Exception e) {
              e.printStackTrace();
          }
       }
   
   
       public static void main(String args[])  {
         try {
           // test_text_protocol();
           useVC = 1;
           test_text_protocol();
           test_binary_protocol();
           System.out.println("jdbc test pass");
           // sleep(600000);
         } catch (Exception e) {
           e.printStackTrace();
         }
       }
   }
   

2. 编译 TestOBClientVC

   javac -cp ./oceanbase-client-2.4.1.jar TestOBClientVC.java
   

3. 执行 TestOBClientVC

   java -cp $CLASSPATH:oceanbase-client-2.4.1.jar TestOBClientVC