SQL on Oracle

概述

SQL on Oracle是Extension Connector的功能之一，支持openGauss数据库实例发送SQL语句给Oracle数据库（称为“目标库”）执行，并获取执行结果。执行结果可以参与本地表关联查询或者入本地表及本地文件系统。

支持的Oracle版本

支持连接Oracle11.2.0.1至Oracle12.2.0.1。

Oracle的odbc驱动版本要求是12.2.0.1.0。

支持的Oracle数据类型

Oracle到openGauss的数据类型转换关系如表1所示。

表 1 Oracle到openGauss的数据类型转换关系

类型分类

目标Oracle数据类型

本地openGauss数据类型

NUMERIC

NUMBER(p,s), p<=38, s>=0

NUMERIC(p,s)

NUMBER(p,s), p<=38, s<0

NUMERIC(p,0)

NUMBER(p,0), p<=4

SMALLINT

NUMBER(p,0), p<=9

INTEGER

NUMBER(p,0), p<=18

BIGINT

BINARY_FLOAT

FLOAT4

BINARY_DOUBLE

BINARY_DOUBLE

STRING

CHAR

TEXT

CHAR(n)

VARCHAR2

DATE

TIMESTAMP[(p)], p<=6

TIMESTAMP

TIMESTAMP[(p)] WITH TIME ZONE, p<=6

TIMESTAMP WITH TIME ZONE

DATE

DATE

SQL on Oracle - 图1 须知：

  • 对于Oracle返回的数据类型，需要使用上表中对应的类型去接收，即在AS子句中指定。如果Oracle返回的类型不在上表中，或没有按照指定对应关系去接收，则可能会出现结果不正确或转换失败。比如Oracle的任意数值类型NUMBER是不在支持范围内的。
  • 待返回的Oracle数据中不可含有NAN或INF。
  • Oracle端数据类型定义为CHAR(n)时，对于字符串长度小于n的情况会自动补齐空格，当这种数据传输到openGauss并转换为text类型时，字符串尾部的空格保留。
  • openGauss的编码方式设置为SQL_ASCII时，length()函数返回的是字符串数据的字节数，而不是实际的字符数。因此查询exec_on_extension返回数据的length时请注意，如： select c2,length(c2) from exec_on_extension(‘oracle’,’select * from a;’) as (c1 int, c2 text); 返回的第二列就是字符串的字节数，而不是实际字符数。
  • 对于TIMESTAMP[(p)] WITH TIME ZONE的数据类型，要求Oracle数据库的时区和本地数据库的时区设置一致，否则可能出现结果错误。

使用前的对接配置

SQL on Oracle需要使用标准的unixODBC-2.3.6和Oracle ODBC-12.2连接Oracle。使用前需按以下步骤准备：

  1. 以操作系统用户omm登录数据库主节点。

    在该节点上执行以下步骤2-步骤7，中间不要切换节点。

  2. （可选）配置Data Source密钥文件。

    该密钥文件将用于加密Data Source对象中的敏感字段username/password。若不配置系统会默认使用$GAUSSHOME/bin中server的密钥文件：server.key.cipher和server.key.rand。

    1. 使用gs_guc工具生成密钥文件。

      1. gs_guc encrypt –M source –K ‘用户密钥串’ –D  ‘密钥文件存放目录’
      • 用户密钥串需至少包含3种字符，且不少于8个字符。
      • 生成后的密钥文件有两个，分别为datasource.key.cipher和datasource.key.rand。文件名称需固定不可变更。
      • datasource.key.cipher和datasource.key.rand这两个文件，需分发到数据库实例各节点的$GAUSSHOME/bin下。

    2. 将密钥文件放入指定位置$GAUSSHOME/bin下。然后使用gs_om ec工具将密钥文件发送到数据库实例其他节点。

      1. gs_om -t ec -m install --key-files --force

      更多详细信息请参考《工具参考》中“服务端工具 > gs_om”章节。

  3. 准备package.zip压缩包。安装配置方法可参考如下：

    1. 前往Oracle官网（http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html）下载如下三个oracle压缩包。放置于GAUSSHOME/utilslib/fcconf/GAUSSHOME/utilslib/fcconf/DSN下。路径不存在部分用户可自行创建，$DSN是以DSN为名的文件夹。DSN名必须由字母，数字，下划线组成。

      • oracle-instantclient-basic-linux.x64-12.2.0.1.0.zip
      • oracle-instantclient-sqlplus-linux.x64-12.2.0.1.0.zip
      • oracle-instantclient-odbc-linux.x64-12.2.0.1.0.zip

    2. 打包三个oracle压缩至package.zip。

      1. cd $GAUSSHOME/utilslib/fc_conf/$DSN
      2. zip -r package.zip oracle-instantclient-basic-linux.x64-12.2.0.1.0.zip oracle-instantclient-sqlplus-linux.x64-12.2.0.1.0.zip oracle-instantclient-odbc-linux.x64-12.2.0.1.0.zip

  4. 配置Oracle数据库侦听参数并打开侦听进程。

    可参考如下设置。

    1. 设置listener.ora文件（添加侦听列表）：

      1. cd $ORACLE_HOME/network/admin
      2. vim listener.ora

      在文件中输入类似以下配置信息（如果已有则不用重复添加）：

      1. # ORACLE_HOME指定的目录，请根据实际修改。
      2. # ORCL是Oracle数据库的实例名称，也是准备连接的实例，请根据实际修改。
      3. SID_LIST_LISTENER =
      4.   (SID_LIST =
      5.     (SID_DESC =
      6.       (SID_NAME = ORCL)
      7.       (ORACLE_HOME =/opt/oracle/db/product/11.1.0/db)
      8.       (PROGRAM = extproc)
      9.     )
      10.     (SID_DESC =
      11.       (SID_NAME = ORCL)
      12.       (ORACLE_HOME =/opt/oracle/db/product/11.1.0/db)
      13.     )
      14.   )
      16. # HOST和PORT分别是Oracle数据库的主机IP地址和端口号，请根据实际修改。
      18. LISTENER =
      19.   (DESCRIPTION_LIST =
      20.     (DESCRIPTION =
      21.       (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1521))
      22.       (ADDRESS = (PROTOCOL = TCP)(HOST = XX.XX.XX.XX)(PORT = XXXX))
      23.     )
      24.   )
      26. # /opt/oracle/db是Oracle数据库的安装目录，不是ORACLE_HOME，请根据实际修改。
      27. ADR_BASE_LISTENER = /opt/oracle/db

    2. 设置tnsnames.ora文件（添加数据库实例）：

      1. cd $ORACLE_HOME/network/admin
      2. vim tnsnames.ora

      在文件中添加如下数据库实例，（如已有则不用重复添加）：

      1. # ORCL是数据库实例名称，也是准备连接的实例，请根据实际修改。
      2. # HOST和PORT分别是Oracle数据库的主机IP地址和端口号，请根据实际修改。
      4. ORCL =
      5.   (DESCRIPTION =
      6.     (ADDRESS = (PROTOCOL = TCP)(HOST = XX.XX.XX.XX)(PORT = XXXX))
      7.     (CONNECT_DATA =
      8.       (SERVER = DEDICATED)
      9.       (SERVICE_NAME = ORCL)
      10.     )
      11.   )

    3. 查看侦听状态：

      通过lsnrctl命令，status是查看状态，start是打开侦听，stop是关闭侦听。以下是数据库实例ORCL处于侦听状态的示例：

      1. lsnrctl
      2. LSNRCTL> status
      3. ...
      4. Listening Endpoints Summary...
      5.   (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC1521)))
      6.   (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=linux-ss3q)(PORT=1521)))
      7. Services Summary...
      8. Service "orcl" has 1 instance(s).
      9.   Instance "orcl", status READY, has 1 handler(s) for this service...
      10. Service "orclXDB" has 1 instance(s).
      11.   Instance "orcl", status READY, has 1 handler(s) for this service...
      12. The command completed successfully

      也可以直接在终端上输入：

      1. lsnrctl stop      # 停止侦听。
      2. lsnrctl start     # 打开侦听。

    4. **（可选）**配置安全连接：

      以Network Data Encryption为例，详细的配置和可选加密方法请参考Oracle文档：

      https://docs.oracle.com/cd/E11882_01/network.112/e40393/asoconfg.htm#ASOAG020

      下面给出其中一种AES256的配置方法：

      a) 配置Server端（Oracle数据库）。

      修改配置文件sqlnet.ora

      1. cd $ORACLE_HOME/network/admin
      2. vim sqlnet.ora

      若要求采用AES256方法加密连接Server，在文件末尾追加内容（如已有则无需重复添加）：

      1. SQLNET.ENCRYPTION_SERVER=REQUIRED
      2. SQLNET.ENCRYPTION_TYPES_SERVER=(AES256)

      b) 配置Client端（本地openGauss数据库实例）。

      修改文件$GAUSSHOME/utilslib/instantclient_12_2/network/admin/sqlnet.ora，首次需要添加该文件，其中内容如下：

      1. # NAMES.DIRECTORY_PATH指定解析方法
      2. # ADR_BASE是Oracle的本地家目录，就是ODBC的目录
      3. # 加密方法需要和Server端一致，此处是AES256
      4. NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)
      5. SQLNET.ENCRYPTION_CLIENT=REQUIRED
      6. SQLNET.ENCRYPTION_TYPES_CLIENT=(AES256)
      7. ADR_BASE = $GAUSSHOME/utilslib/instantclient_12_2  # 环境变量需展开为绝对路径

      修改文件$GAUSSHOME/utilslib/instantclient_12_2/network/admin/tnsnames.ora，首次需要添加该文件，其中内容如下：

      1. # HOST和PORT分别是Oracle数据库的主机IP地址和端口号
      2. # SERVICE_NAME=ORCL是Oracle具体实例名称
      3. # Remote_ORCL是用户自己重命名的实例名，加密连接时需要指定该实例名称
      4. Remote_ORCL =
      5.   (DESCRIPTION =
      6.     (ADDRESS_LIST=
      7.         (ADDRESS = (PROTOCOL = TCP)(HOST = XX.XX.XX.XX)(PORT = XXXX))
      8.     )
      9.     (CONNECT_DATA =
      10.       (SERVER = DEDICATED)
      11.       (SERVICE_NAME = ORCL)
      12.     )
      13.   )

      如果是首次添加这两个文件，则需要保证数据库实例用户至少拥有读写权限：

      1. cd $GAUSSHOME/utilslib/instantclient_12_2/
      2. chmod -R 700 network

      SQL on Oracle - 图2 说明： 为了数据传输的安全性考虑，建议用户配置此安全连接。

  5. 设置DSN配置文件。

    进入GAUSSHOME/utilslib/fcconf/GAUSSHOME/utilslib/fcconf/DSN，创建配置文件DSN.ini，文件内容需确保正确，其内容可参考如下。其中GAUSSHOME和GAUSSHOME和DSN替换成相应内容。

    • 配置安全连接时，添加内容（’#’及其后面的内容不要）:

      1. [oracle]                               # DSN
      2. Driver=Oracle ODBC driver              # Oracle ODBC名称
      3. Servername=Remote_ORCL                 # 用户自定义实例名
      4. Database=orcl                          # 待连接的Oracle实例名称
      5. Port=XXXX                              # Oracle的端口号

    • 不配置安全连接时，添加内容（’#’及其后面的内容不要）:

      1. [oracle]                                # DSN
      2. Driver=Oracle ODBC driver               # Oracle ODBC名称
      3. Servername=//XX.XX.XX.XX:XXXX/orcl      #//Oracle主机IP地址:端口号/实例名称
      4. Database=orcl                           # 待连接的Oracle实例名称
      5. Port=XXXX                               # Oracle的端口号

      创建Data Source时，其中的dsn字段就是此处DNS.ini文件中的”oracle”.

  6. 执行如下命令完成自动化部署。

    安装之前确保待分发文件有足够的权限（数据库实例用户至少拥有读写权限）。随后调用命令，命令如下。

    1. gs_om -t ec -m add -N DSN -U username --type=oracle
    2. gs_om -t ec -m add -N DSN -U username --type=oracle -L  # -L为本地模式

    SQL on Oracle - 图3 说明： 使用本地模式时，需要在各个节点上分别执1-5。

  7. 安装unixODBC（仅在Oracle中有中文字符时，EC对接才需要执行此步骤）。

    unixODBC的安装推荐使用源码进行安装。

    源码可在http://www.unixodbc.org/或https://sourceforge.net/projects/unixodbc/files/unixODBC/进行下载。

    建议使用2.3.6版本。推荐如下方法进行unixODBC安装部署：

    a) 下载并解压。

    1. tar -xzvf unixODBC-2.3.6.tar.gz
    2. cd unixODBC-2.3.6

    b) configure（需要gcc）。

    使用以下命令对unixODBC进行configure操作。其中，prefix为用户指定安装目录，此处的安装目录为临时的，建议指定一个空目录。

    1. ./configure --enable-gui=no --prefix=/tmp/unixODBC-2.3.6 --enable-iconv=yes --with-iconv-char-enc=enc

    SQL on Oracle - 图4 说明：

    • 实际部署时，编译参数—with-iconv-char-enc=enc中的enc需要替换为Oracle数据库的字符集编码。
    • 常见的Oracle数据库中文字符编码有AL32UTF8和ZHS16GBK。
    • 如果Oracle字符编码为AL32UTF8，建议编译参数设置为—with-iconv-char-enc=UTF8
    • 如果Oracle字符编码为ZHS16GBK，建议编译参数设置为—with-iconv-char-enc=GB18030

    c) 编译安装。

    1. make
    2. make install

    d) 拷贝unixODBC到指定的安装目录。

    1. cd /tmp/unixODBC-2.3.6
    2. rm -rf $GPHOME/unixodbc/*
    3. cp -r /tmp/unixODBC-2.3.6/* $GPHOME/unixodbc/

    e) 修改$GPHOME/unixodbc/路径下的文件权限和属主。

    1. chmod -R 700 $GPHOME/unixodbc/*
    2. chown -R user:group $GPHOME/unixodbc/*

    SQL on Oracle - 图5 说明： 实际部署时使用数据库实例安装用户和属主替换命令行中的user:group

    f) 设置unixODBC配置文件 。参考4。(/usr/local/etc/ 替换成$GPHOME/unixodbc/etc/)

    g) 设置环境变量。参考7

    修改$GAUSSHOME/utilslib/env_ec，修改或者追加环境变量NLS_LANG设置。

    SQL on Oracle - 图6 说明： 可以登录Oralce数据库，执行如下语句查询NLS_LANG的值：

    1. SELECT userenv('language') FROM sys_dummy;

    h) 把步骤d中的unixODBC文件拷贝到数据库实例的其它数据节点的$GPHOME/unixodbc/路径下，并执行步骤e和步骤f修改文件权限、属主，并配置环境变量。

    SQL on Oracle - 图7 说明： 对于OS异构的数据库实例，需要根据OS把节点分组，然后每组单独编译unixODBC（执行步骤b到步骤g）

  8. 执行如下命令，重启数据库实例，终止om_monitor进程，以使openGauss的进程感知到环境变量的变化。

    1. gs_om -t ec -m restart -U username
    2. gs_om -t ec -m restart -U username -L   #-L为本地模式
    3. gs_om -t stop && gs_om -t start         #仅本地模式执行

    SQL on Oracle - 图8 说明：

    • 使用本地模式时，需要在各个节点上分别执步骤1-6。
    • 因为本地模式不启停数据库实例，因此需要手动进行启停数据库实例。

  9. 创建Data Source。

    可以参考如下操作：

    1. 连接数据库。

    2. 创建Data Source。

      1. postgres=# CREATE DATA SOURCE ds_oracle TYPE 'ORACLE' OPTIONS (DSN 'oracle', USERNAME 'oracle_user', PASSWORD 'oracle_pwd', ENCODING 'UTF8');

      其OPTIONS中DSN字段为odbc.ini中对应Oracle数据库的DSN（在上一个步骤中即是’oracle’），USERNAME和PASSWORD字段分别为Oracle数据库的待访问实例ORCL（odbc.ini中的database）的用户名和密码，ENCODING字段为Oracle字符集的编码方式。

      如果需要修改ds_oracle中的PASSWORD为’new_pwd’，则可做如下操作：

      1. postgres=# ALTER DATA SOURCE ds_oracle OPTIONS (SET PASSWORD 'new_pwd');

      SQL on Oracle - 图9 说明：

      • 无论用户是否配置了Data Source密钥文件。创建和修改Data Source时，此处提供的Oracle数据库用户名和密码在openGauss数据库实例中都将被加密保存到系统表pg_extension_data_source中。
      • 如果Oracle的字符集为中文字符集，必须保证data source定义中ENCODING、$GAUSSHOME/utilslib/env_ec中的NLS_LANG设置、unixODBC编译参数—with-iconv-char-enc指定的encoding三者完全一致。
      • 如果Oracle字符集为中文字符集，推荐本地数据库的字符集编码和远端Oracle的字符集编码保持一致，避免因字符集不兼容转码失败导致的作业执行失败。
      • Data Source创建后，密钥文件不可更改，否则Data Source将无法使用。
      • 用户需要保证package.zip中的内容完整，DSN.ini中的内容正确。安装部署完成后不进行修改，否则搭建好的环境有无法正常使用的风险。
      • 创建的DATA SOURCE需要和odbc.ini中的配置保持一致，不然会导致无法找到数据源。

  10. 连接Oracle数据库。

    完成以上配置后，在数据库实例正常的情况下，即可连接openGauss数据库，对Oracle数据库进行SQL操作。比如查询Oracle的一张表a(c1 number(9,0))：

    1. postgres=# SELECT * FROM exec_on_extension('ds_oracle', 'select * from a;') AS (c1 int);

    SQL on Oracle - 图10 说明：

    • 使用exec_on_extension之前需要创建Data Source对象。
    • 当发送的SQL语句在Oracle执行失败时，连接函数exec_on_extension也是执行失败。

注意事项

  1. 目录$GAUSSHOME/utilslib和其中的文件env_ec使用约束请参考《工具参考》中“服务端工具 > gs_om”章节。

  2. 需要注意数据库实例用户对目录GAUSSHOME/utilslib（包括其中的内容）和文件GAUSSHOME/utilslib（包括其中的内容）和文件GAUSSHOME/bin/datasource.key.*至少具备读写权限。建议在每次使用gs_om ec工具之前确保数据库实例用户的读写权限，然后再安装部署，否则可能会引起升级、扩容等操作的失败。

  3. gs_om ec工具分发的相对位置是指GAUSSHOME/utilslib/fcconf/GAUSSHOME/utilslib/fcconf/DSN（Data Source密钥文件除外），与当前所在位置无关，即：在任一目录下执行下面命令意义一样，都是安装在GAUSSHOME/utilslib/fcconf里面的GAUSSHOME/utilslib/fcconf里面的DSN下。

    1. gs_om -t ec -m add -N DSN -U username --type=oracle

  4. 数据库实例管理员创建一个Data Source对象（对应某一个DSN），然后将该Data Source对象的使用权限赋予某一个用户，则该用户通过exec_on_extension就可以访问odbc.ini中这个DSN对应的远端数据库了。

示例

  1. -- 创建Data Source（这里的username/password是指待连接的Oracle数据库的用户名/密码）
  2. postgres=# CREATE DATA SOURCE oracle VERSION '11g' OPTIONS (dsn 'oracle', username 'user_ora', password 'pwd_ora', encoding 'utf8');
  5. -- 建远程表、插入数据、查询数据
  6. postgres=# SELECT * FROM exec_on_extension('oracle', 'create table a (c1 int);') AS (c1 text);
  7.  c1 
  8. ----
  9. (0 rows)
  10. postgres=# SELECT * FROM exec_on_extension('oracle', 'insert into a values (119);') AS (c1 text);
  11.  c1 
  12. ----
  13. (0 rows)
  14. postgres=# SELECT * FROM exec_on_extension('oracle', 'insert into a select * from a;') AS (c1 text);
  15.  c1 
  16. ----
  17. (0 rows)
  18. postgres=# SELECT * FROM exec_on_extension('oracle', 'select * from a;') AS (c1 int);
  19.  c1  
  20. -----
  21.  119
  22.  119
  23. (2 rows)
  24. postgres=# SELECT * FROM exec_on_extension('oracle', 'select * from a a1 inner join a a2 on a1.c1=a2.c1;') AS (c1 int, c2 int);
  25.  c1  | c2  
  26. -----+-----
  27.  119 | 119
  28.  119 | 119
  29.  119 | 119
  30.  119 | 119
  31. (4 rows)
  33. -- 查询结果入本地表
  34. postgres=# CREATE TABLE b AS SELECT * FROM exec_on_extension('oracle', 'select * from a group by c1;') AS (c1 int);
  35. NOTICE:  The 'DISTRIBUTE BY' clause is not specified. Using 'c1' as the distribution column by default.
  36. HINT:  Please use 'DISTRIBUTE BY' clause to specify suitable data distribution column.
  37. INSERT 0 1
  38. postgres=# INSERT INTO b SELECT * FROM exec_on_extension('oracle', 'select * from a group by c1;') AS (c1 int);
  39. INSERT 0 1
  41. -- 查询结果与本地表关联查询
  42. postgres=# SELECT * FROM b INNER JOIN (SELECT * FROM exec_on_extension('oracle', 'select * from a;') AS (c1 int)) a ON a.c1=b.c1;
  43.  c1  | c2  
  44. -----+-----
  45.  119 | 119
  46.  119 | 119
  47.  119 | 119
  48.  119 | 119
  49. (4 rows)
  51. -- 其他用户使用该Data Source
  52. postgres=# CREATE USER tmp_usr IDENTIFIED BY 'Gs@123456';
  54. postgres=# GRANT USAGE ON DATA SOURCE oracle TO tmp_usr;
  56. postgres=# \c - tmp_usr
  57. postgres=#  SELECT * FROM exec_on_extension('oracle', 'select * from a group by c1;') AS (c1 int);
  58.  c1  
  59. -----
  60.  119
  61. (1 row)
  63. -- 清除Data Source、表和用户
  64. postgres=# \c - omm
  65. postgres=# SELECT * FROM exec_on_extension('oracle', 'drop table a;') AS (c1 text);
  66.  c1 
  67. ----
  68. (0 rows)
  69. postgres=# DROP DATA SOURCE oracle;
  71. postgres=# DROP TABLE b;
  73. postgres=# DROP USER tmp_usr;

异常处理

EC对接openGauss时产生的常见异常，请参见表2。

表 2 常见EC对接openGauss的异常处理

异常分类

报错信息

异常处理

部署异常

[GAUSS-50201] : The $GAUSSHOME/utilslib/fc_conf/ora/ does not exist.

查看自动化部署log，根据日志中的报错信息，处理异常。解决异常后重新进行部署。

log所在路径如下：

  • 默认路径为$GAUSSLOG/om。
  • 使用gs_om工具进行自动化部署时，如果指定了-l参数，则日志存放在指定位置。

连接异常

ERROR: source “spark_ds” does not exist

需要创建DATA SOURCE，创建语句请参考CREATE DATA SOURCE。

执行异常

ERROR: invalid input syntax for integer

查看EC支持的LirbA数据类型。请参见表1。

执行异常

ERROR: dn_6033_6034: DSN:oracle,Fail to exec SQL with the ODBC connection! Detail can be found in node log of ‘dn_6033_6034’.

DETAIL: [Oracle][ODBC][Ora]ORA-00942: table or view does not exist

如果执行的SQL中有表或者视图的定义不存在，就会出现这类报错。EC会将Oracle端的错误返回到EC端，如果SQL在Oracle端执行时有其他语法报错，EC也会报出相关错误信息。

相关链接

CREATE DATA SOURCE，SQL on Spark，SQL on other openGauss，《工具参考》中“服务端工具 > gs_om”章节