华为云用户手册

  • 请求示例 批量创建CA标签,请求头中的X-Auth-Token字段需要填写token,且该token需要具有本API的访问权限。 POST https://{Endpoint}/v1/private-certificate-authorities/4c0e772e-a30c-4029-b929-b7acb04143f7/tags/create { "tags" : [ { "key" : "key1", "value" : "value1" }, { "key" : "key2", "value" : "value2" } ] }
  • 响应参数 状态码: 400 表5 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024 状态码: 401 表6 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024 状态码: 403 表7 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024 状态码: 404 表8 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024 状态码: 500 表9 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024
  • 请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 用户Token。 通过调用 IAM 服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。 最小长度:32 最大长度:2097152 表3 请求Body参数 参数 是否必选 参数类型 描述 tags 是 Array of ResourceTag objects 标签列表,key和value键值对的集合。 数组长度:1 - 20 表4 ResourceTag 参数 是否必选 参数类型 描述 key 是 String 标签键。 可用UTF-8格式表示的字母(包含中文、西班牙语、葡语等)、数字和空格,以及以下字符: _ . : = + - @ 最小长度:1 最大长度:128 value 是 String 标签值。 可用UTF-8格式表示的字母(包含中文、西班牙语、葡语等)、数字和空格,以及以下字符: _ . : / = + - @ 最小长度:0 最大长度:255
  • 响应示例 状态码:200 正常返回。 { "request_info" : "success" } 状态码:401 认证失败。 { "error_code" : "SCM.XXX", "error_msg" : "XXX" } 状态码:403 禁止访问。 { "error_code" : "SCM.XXX", "error_msg" : "XXX" } 状态码:500 请求未完成,服务器内部异常。 { "error_code" : "SCM.XXX", "error_msg" : "XXX" }
  • 请求示例 { "domain" : "www.test.com", "company_name" : "xx公司", "company_province" : "四川", "company_city" : "成都", "applicant_name" : "xx", "applicant_phone" : "12312345678", "applicant_email" : "example@test.com", "csr" : "", "sans" : "", "country" : "CN", "company_unit" : "IT", "contact_name" : "test", "contact_phone" : "12312345678", "contact_email" : "example@test.com", "auto_dns_auth" : false, "agree_privacy_protection" : true }
  • 请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 用户Token。 通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。 最小长度:32 最大长度:2097152 表3 请求Body参数 参数 是否必选 参数类型 描述 domain 是 String 该证书绑定的 域名 。 当购买的证书为“单域名”或“泛域名”类型的证书时,请直接填写单域名或泛域名即可。 当购买的证书为“多域名”类型的证书时,需要选择1个域名作为主域名。 示例:www.example.com 最小长度:0 最大长度:255 sans 否 String 绑定多域名类型证书的附加域名。 当购买的证书为“多域名”类型的证书,且有可增加附加域名的额度时,才需要设置该值。 多个域名需要以“;”隔开。 示例:www.example.com;www.example1.com;www.example2.com 最小长度:0 最大长度:4096 csr 否 String 证书 CS R串,与域名必须匹配。 最小长度:0 最大长度:5120 company_name 否 String 公司名称,OV和EV型证书必填。字符长度为0~63位。 最小长度:0 最大长度:63 company_unit 否 String 部门名称。字符长度为0~63位。 最小长度:0 最大长度:63 company_province 否 String 公司所在省份,OV和EV型证书必填。字符长度为0~63位。 最小长度:0 最大长度:63 company_city 否 String 公司所在市区,OV和EV型证书必填。字符长度为0~63位。 最小长度:0 最大长度:63 country 否 String OV和EV型证书必填,国家编码,需符合正则"[A-Za-z]{2}"。 最小长度:2 最大长度:2 applicant_name 是 String 申请人的姓名。请输入中文、英文字符,下划线,中划线,英文逗号,英文句点,且长度为4到100字节。 最小长度:0 最大长度:63 applicant_phone 是 String 申请人的电话号码。示例:13212345678 最小长度:0 最大长度:63 applicant_email 是 String 申请人的邮箱。示例:example@huawei.com 最小长度:0 最大长度:256 contact_name 否 String 技术联系人的姓名。字符长度为0~63位。 最小长度:0 最大长度:63 contact_phone 否 String 技术联系人的电话号码。示例:13212345678 最小长度:0 最大长度:63 contact_email 否 String 技术联系人的邮箱。示例:example@huawei.com 最小长度:0 最大长度:256 auto_dns_auth 否 Boolean 是否将DNS验证信息推送到华为云解析服务。 true:推送。 false:不推送。 agree_privacy_protection 是 Boolean 是否同意授权隐私协议。此处仅能设置为true才能成功申请证书。 true:同意隐私协议。 false:不同意隐私协议。 domain_method 是 String 域名验证方式。 DNS:DNS验证,指在域名管理平台通过解析指定的DNS记录,验证域名所有权。 FILE:文件验证,指通过在服务器上创建指定文件的方式来验证域名所有权。 EMAIL:邮箱验证,指登录域名管理员邮箱,接收域名确认邮件并根据提示进行操作来验证域名所有权。 DV域名型和DV基础版证书(GeoTrust入门级SSL证书和DigiCert 免费SSL证书 )默认通过“DNS验证”方式进行验证。 纯IP(公网IP)的证书仅支持通过“文件验证”方式进行验证,且仅纯IP证书支持“文件验证”方式验证。 最小长度:0 最大长度:32 key_algorithm 否 String 密钥算法。默认RSA_2048 最小长度:0 最大长度:32
  • 响应参数 状态码:200 表4 响应Body参数 参数 参数类型 描述 request_info String 请求结果。 最小长度:0 最大长度:63 状态码:401 表5 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024 状态码:403 表6 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024 状态码:500 表7 响应Body参数 参数 参数类型 描述 error_code String 错误请求返回的错误码。 最小长度:3 最大长度:36 error_msg String 错误请求返回的错误信息。 最小长度:0 最大长度:1024
  • 使用限制 单账号跟踪的事件可以通过 云审计 控制台查询。多账号的事件只能在账号自己的事件列表页面去查看,或者到组织追踪器配置的OBS桶中查看,也可以到组织追踪器配置的 CTS /system日志流下面去查看。 用户通过云审计控制台只能查询最近7天的操作记录。如果需要查询超过7天的操作记录,您必须配置转储到 对象存储服务 (OBS)或 云日志 服务(LTS),才可在OBS桶或LTS日志组里面查看历史事件信息。否则,您将无法追溯7天以前的操作记录。 云上操作后,1分钟内可以通过云审计控制台查询管理类事件操作记录,5分钟后才可通过云审计控制台查询数据类事件操作记录。 CTS新版事件列表不显示数据类审计事件,您需要在旧版事件列表查看数据类审计事件。 云审计控制台对用户的操作事件日志保留7天,过期自动删除,不支持人工删除。
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-3.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB _driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • 配置JDK环境 客户端需配置JDK1.8。JDK是跨平台的,支持Windows、Linux等多种平台。以Windows为例,配置方法如下。 在DOS窗口(Windows下的命令提示符)输入以下命令查看JDK版本。 java -version 确认是否已安装JDK1.8。如果未安装JDK,请从官方网站下载安装包并安装。 根据如下步骤配置系统环境变量。 右键单击“我的电脑”,选择“属性”。 在“系统”页面左侧导航栏单击“高级系统设置”。 在“系统属性”页面,“高级”页签上单击“环境变量”。 在“环境变量”页面上,“系统变量”区域单击“新建”或“编辑”配置系统变量。变量说明如表2所示。 表2 变量说明 变量名 操作 变量值 JAVA_HOME 若存在,则单击“编辑”。 若不存在,则单击“新建”。 JAVA的安装目录。 例如:C:\Program Files\Java\jdk1.8.0_131 Path 单击“编辑”。 若配置了JAVA_HOME,则在变量值的最前面加上: %JAVA_HOME%\bin 若未配置JAVA_HOME,则在变量值的最前面加上JAVA安装的全路径: C:\Program Files\Java\jdk1.8.0_131\bin CLASSPATH 单击“新建”。 %JAVA_HOME%\lib;%JAVA_HOME%\lib\tools.jar
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-3.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB_driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-3.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB_driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • 获取ODBC包以及依赖库 ODBC包以及依赖库支持两种操作系统(Linux和Windows),请用户根据实际情况进行选择。 Linux系统: 从驱动包中获取,包名为GaussDB-Kernel_数据库版本号_操作系统版本号_64bit_Odbc.tar.gz。Linux环境下,开发应用程序要用到unixODBC提供的头文件(sql.h、sqlext.h等)和库libodbc.so。 这些头文件和库可从unixODBC-2.3.7的源码包中获得。 Windows系统: 从驱动包中获取,包名为GaussDB-Kernel_数据库版本号_Windows_X86_Odbc.tar.gz(32位)和GaussDB-Kernel_数据库版本号_Windows_X64_Odbc.tar.gz(64位)。 Windows环境下,开发应用程序用到的相关头文件和库文件由系统自带。
  • 环境类 Go环境配置 用户需要在环境变量中配置以下参数: GO111MODULE:用户使用在线导入的方式安装Go驱动时需要设置GO111MODULE为on。如果不希望进行go mod工程的改造,需将GO111MODULE设置为off,并手动下载依赖包。依赖包与驱动根目录和业务代码保持同级。 GOPROXY:用户使用在线导入时需配置包含Go驱动包的路径。 用户可以根据自己场景参数配置Go其他相关环境变量。 通过go env查看Go环境变量配置结果,并且查看Go版本是否在1.13或以上。 Go驱动安装 从驱动包中获取Go驱动包到本地。包名为GaussDB-Kernel_数据库版本号_操作系统版本号_64bit_Go.tar.gz。解压后为Go驱动源码包。 进入Go驱动代码根路径,执行go mod tidy下载相关依赖,需要在环境变量中配置GOPATH=${Go驱动依赖包存放路径}。 若依赖已下载至本地,可以在go.mod里面添加一行“通过replace将Go驱动包替换为本地Go驱动包地址”,表示代码里面所有的import Go驱动包都是走本地路径, 同时依赖也不会从代理里下载。 通过go mod tidy下载相关依赖时,可能会下载某个依赖的低版本,如果依赖的低版本存在漏洞,可以通过更改go.mod文件中对应依赖的版本号的方式,更新依赖到漏洞修复后的版本进行规避风险。 用户不涉及驱动开发,调用Go 1.13版本或以上即可,runtime运行库需要更新至1.18版本及以上。
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-3.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB_driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-3.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB_driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • INSERT 【规格】INSERT ON DUPLICATE KEY UPDATE不支持对主键或唯一约束的列上执行UPDATE。 INSERT ON DUPLICATE KEY UPDATE的语义是对唯一约束冲突的行进行更新,这个过程中不应对约束的值进行更新。 【规则】禁止对存在多个唯一约束的表执行INSERT ON DUPLICATE KEY UPDATE。 表中存在多个唯一约束包括存在多个唯一索引,或既存在主键(PRIMARY KEY),又存在唯一索引(UNIQUE INDEX)两种情况。当存在多个唯一约束时,会默认检查所有的唯一约束条件,只要任何一个约束存在冲突,就会对冲突行进行更新,即可能更新多条记录,与业务预期不相符。业务应给予更加明确的插入更新条件。 【建议】对于批量插入的情况,建议使用executeBatch执行INSERT INTO VALUES (?),执行效率将高于执行多条INSERT INTO VALUES(?)或INSERT INTO VALUES(?),...,(?)。 父主题: 数据库编程规范
  • 解压驱动包 解压获取到的驱动包,找到名为GaussDB-Kernel_数据库版本号_操作系统_64bit_Jdbc.tar.gz的JDBC驱动包并解压,解压后,可获得以下驱动jar包: gsjdbc4.jar:该驱动包适用于从PostgreSQL迁移业务的场景,驱动类和加载路径与迁移前保持一致,但接口支持情况不完全一致,未支持的接口需要业务侧进行调整。 opengaussjdbc.jar:主类名为“com.huawei.opengauss.jdbc.Driver”,数据库连接的url前缀为“jdbc:opengauss”,推荐使用此驱动包。如果遇到同一JVM进程内需要同时访问PostgreSQL及GaussDB的场景,请使用此驱动包。 各驱动包只是驱动类加载路径和url前缀不同,接口功能上相同。 jdbc发布件jar包按照架构分类,gscejdbc.jar包必须与对应的部署环境一致才能使用,其他jar包无需与部署环境一致。 gsjdbc200.jar:该驱动包适用于从Gauss200迁移业务的场景,驱动类和加载路径与迁移前保持一致,但接口支持情况不完全一致,未支持的接口需要业务侧进行调整。 不能使用gsjdbc4的驱动包操作PostgreSQL数据库,虽然部分版本能够建连成功,但部分接口行为与PostgreSQL JDBC不同,可能导致未知错误。 不能使用PostgreSQL的驱动包操作 GaussDB数据库 ,虽然部分版本能够建连成功,但部分接口行为与GaussDB JDBC不同,可能导致未知错误。
  • 驱动类 在创建数据库连接之前,需要加载数据库驱动类“org.postgresql.Driver”(对应包gsjdbc4.jar)。 由于GaussDB在JDBC的使用上与PG的使用方法保持兼容,所以同时在同一进程内使用两个JDBC的驱动的时候,可能会类名冲突。 本版本JDBC不再支持IAM认证功能。 相比于PG驱动,GaussDB JDBC驱动主要做了以下特性的增强: 支持SHA256加密方式登录。 支持对接实现sf4j接口的第三方日志框架。 支持连接级别的分布式负载均衡。 支持容灾切换。
  • 环境类 客户端需配置JDK1.8。JDK是跨平台的,支持Windows、Linux等多种平台,下面以Windows为例,介绍JDK配置流程: DOS窗口(windows下的命令提示符)输入“java -version”,查看JDK版本,确认为JDK1.8版本。如果未安装JDK,请下载安装包并安装。 在windows操作系统桌面中“此电脑”图标上单击右键,选择“属性”。 在弹出的“系统”窗口中,单击左侧导航栏中“高级系统设置”。 在弹出的“系统属性”窗口中,单击右下角的“环境变量”。 在弹出的“环境变量”窗口中的“系统变量”区域框中设置如下变量名和变量值。 变量名 操作 变量值 JAVA_HOME 若存在,则单击“编辑”。 若不存在,则单击“新建”。 JAVA的安装目录。 例如:C:\Program Files\Java\jdk1.8.0_131 Path 编辑 若配置了JAVA_HOME,则在变量值的最前面加上: %JAVA_HOME%\bin; 若未配置JAVA_HOME,则在变量值的最前面加上 JAVA安装的全路径: C:\Program Files\Java\jdk1.8.0_131\bin; CLASSPATH 新建 .;%JAVA_HOME%\lib;%JAVA_HOME%\lib\tools.jar; 单击“确定”,并依次关闭各窗口。
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-2.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB_driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 --定义函数为SQL查询。 openGauss=# CREATE FUNCTION func_add_sql(integer, integer) RETURNS integer AS 'select $1 + $2;' LANGUAGE SQL IMMUTABLE RETURNS NULL ON NULL INPUT; --利用参数名用 plpgsql 自增一个整数。 openGauss=# CREATE OR REPLACE FUNCTION func_increment_plsql(i integer) RETURNS integer AS $$ BEGIN RETURN i + 1; END; $$ LANGUAGE plpgsql; --返回RECORD类型。 openGauss=# CREATE OR REPLACE FUNCTION compute(i int, out result_1 bigint, out result_2 bigint) RETURNS SETOF RECORD AS $$ BEGIN result_1 = i + 1; result_2 = i * 10; RETURN next; END; $$LANGUAGE plpgsql; --返回一个包含多个输出参数的记录。 openGauss=# CREATE FUNCTION func_dup_sql(in int, out f1 int, out f2 text) AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$ LANGUAGE SQL; openGauss=# SELECT * FROM func_dup_sql(42); --计算两个整数的和,并返回结果。如果输入为null,则返回null。 openGauss=# CREATE FUNCTION func_add_sql2(num1 integer, num2 integer) RETURN integer AS BEGIN RETURN num1 + num2; END; / --创建package属性的重载函数 openGauss=# CREATE OR REPLACE FUNCTION package_func_overload(col int, col2 int) RETURN integer package AS DECLARE col_type text; BEGIN col := 122; dbe_output.print_line('two int parameters ' || col2); return 0; END; / openGauss=# CREATE OR REPLACE FUNCTION package_func_overload(col int, col2 smallint) RETURN integer package AS DECLARE col_type text; BEGIN col := 122; dbe_output.print_line('two smallint parameters ' || col2); RETURN 0; END; / --修改函数add的执行规则为IMMUTABLE,即参数不变时返回相同结果。 openGauss=# ALTER FUNCTION func_add_sql2(INTEGER, INTEGER) IMMUTABLE; --将函数add的名称修改为add_two_number。 openGauss=# ALTER FUNCTION func_add_sql2(INTEGER, INTEGER) RENAME TO add_two_number; --将函数add的属者改为omm。 openGauss=# ALTER FUNCTION add_two_number(INTEGER, INTEGER) OWNER TO omm; --删除函数。 openGauss=# DROP FUNCTION add_two_number; openGauss=# DROP FUNCTION func_increment_sql; openGauss=# DROP FUNCTION func_dup_sql; openGauss=# DROP FUNCTION func_increment_plsql; openGauss=# DROP FUNCTION func_add_sql;
  • 参数说明 function_name 要创建的函数名称(可以用模式修饰)。 取值范围:字符串,要符合标识符命名规范。 argname 函数参数的名称。 取值范围:字符串,要符合标识符命名规范。 argmode 函数参数的模式。 取值范围:IN,OUT,INOUT或VARIADIC。缺省值是IN。只有OUT模式的参数后面能跟VARIADIC。并且OUT和INOUT模式的参数不能用在RETURNS TABLE的函数定义中。 VARIADIC用于声明数组类型的参数。 argtype 函数参数的类型。可以使用%ROWTYPE间接引用表的类型,或者使用%TYPE间接引用表或复合类型中某一列的类型。 expression 参数的默认表达式。 推荐使用方式:将所有默认值参数定义在所有非默认值参数后。 rettype 函数返回值的数据类型。与argtype相同,可以使用%ROWTYPE或者%TYPE间接引用类型。 如果存在OUT或IN OUT参数,可以省略RETURNS子句。如果存在,该子句必须和输出参数所表示的结果类型一致:如果有多个输出参数,则为RECORD,否则与单个输出参数的类型相同。 SETOF修饰词表示该函数将返回一个集合,而不是单独一项。 column_name 字段名称。 column_type 字段类型。 definition 一个定义函数的字符串常量,含义取决于语言。它可以是一个内部函数名称、一个指向某个目标文件的路径、一个SQL查询、一个过程语言文本。 LANGUAGE lang_name 用以实现函数的语言的名称。可以是SQL,C,internal,或者是用户定义的过程语言名称。为了保证向下兼容,该名称可以用单引号(包围)。若采用单引号,则引号内必须为大写。 由于兼容性问题,O风格的语法无论指定任何语言,最终创建的语言都为PL/SQL。 WINDOW 表示该函数是窗口函数,通常只用于C语言编写的函数。替换函数定义时不能改变WINDOW属性。 自定义窗口函数只支持LANGUAGE是internal,并且引用的内部函数必须是窗口函数。 IMMUTABLE 表示该函数在给出同样的参数值时总是返回同样的结果。 STABLE 表示该函数不能修改数据库,对相同参数值,在同一次表扫描里,该函数的返回值不变,但是返回值可能在不同SQL语句之间变化。 VOLATILE 表示该函数值可以在一次表扫描内改变,因此不会做任何优化。 SHIPPABLE NOT SHIPPABLE 表示该函数是否可以下推到DN上执行。 对于IMMUTABLE类型的函数,函数始终可以下推到DN上执行。 对于STABLE/VOLATILE类型的函数,仅当函数的属性是SHIPPABLE的时候,函数可以下推到DN执行。 对于指定了SHIPPABLE/IMMUTABLE的函数或者存储过程,其不能包含EXCEPTION或调用含有EXCEPTION的函数或者存储过程。 PACKAGE 表示该函数是否支持重载。 不允许package函数和非package函数重载或者替换。 package函数不支持VARIADIC类型的参数。 不允许修改函数的package属性。 LEAKPROOF 指出该函数的参数只包括返回值。LEAKPROOF只能由系统管理员设置。 CALLED ON NULL INPUT 表明该函数的某些参数是NULL的时候可以按照正常的方式调用。该参数可以省略。 RETURNS NULL ON NULL INPUT STRICT STRICT用于指定如果函数的某个参数是NULL,此函数总是返回NULL。如果声明了这个参数,当有NULL值参数时该函数不会被执行;而只是自动返回一个NULL结果。 RETURNS NULL ON NULL INPUT和STRICT的功能相同。 EXTERNAL 目的是和SQL兼容,是可选的,这个特性适合于所有函数,而不仅是外部函数。 SECURITY INVOKER AUTHID CURRENT_USER 表明该函数将带着调用它的用户的权限执行。该参数可以省略。 SECURITY INVOKER和AUTHID CURRENT_USER的功能相同。 SECURITY DEFINER AUTHID DEFINER 声明该函数将以创建它的用户的权限执行。 AUTHID DEFINER和SECURITY DEFINER的功能相同。 FENCED NOT FENCED 该参数用于声明函数是在保护模式还是非保护模式下执行。如果函数声明为NOT FENCED模式,则函数的执行在CN或者DN进程中进行。如果函数声明为FENCED模式,则函数在新fork的进程执行,这样函数的异常不会影响CN或者DN进程。 FENCED/NOT FENCED模式的选择: 正在开发或者调试的Function使用FENCED模式。开发测试完成,使用NOT FENCED模式执行,减少fork进程以及通信的开销。 复杂的操作系统操作,例:打开文件,信号处理,线程处理等操作,使用FENCED模式。否则可能影响GaussDB数据库的执行。 用户自定义PL/SQL函数,如果不指定该参数,默认为NOT FENCED,且不支持指定为FENCED执行模式。 COST execution_cost 用来估计函数的执行成本。 execution_cost以cpu_operator_cost为单位。 取值范围:正数 ROWS result_rows 估计函数返回的行数。用于函数返回的是一个集合。 取值范围:正数,默认值是1000行。 configuration_parameter value 把指定的数据库会话参数值设置为给定的值。如果value是DEFAULT或者RESET,则在新的会话中使用系统的缺省设置。OFF关闭设置。 取值范围:字符串 DEFAULT OFF RESET 指定默认值。 FROM CURRENT 取当前会话中的值设置为configuration_parameter的值。 obj_file, link_symbol obj_file指定了动态库的绝对路径;link_symbol指定了该函数的链接符号,即函数在C代码中的函数名称。 plsql_body PL/SQL存储过程体。 当在函数体中进行创建用户、修改密码或加解密等涉及密码或密钥相关操作时,系统表及日志中会记录密码或密钥的明文信息。为防止敏感信息泄露,不建议用户在函数体中进行涉及密码或密钥等敏感信息的相关操作。
  • 注意事项 如果创建函数时参数或返回值带有精度,不进行精度检测。 创建函数时,函数定义中对表对象的操作建议都显式指定模式,否则可能会导致函数执行异常。 在创建函数时,函数内部通过SET语句设置current_schema和search_path无效。执行完函数后的search_path和current_schema与执行函数前的search_path和current_schema保持一致。 如果函数参数中带有出参,SELECT调用函数必须缺省出参,CALL调用函数必须指定出参,对于调用重载的带有PACKAGE属性的函数,CALL调用函数可以缺省出参,具体信息参见CALL的示例。 兼容PostgreSQL风格的函数或者带有PACKAGE属性的函数支持重载。在指定REPLACE的时候,如果参数个数、类型、返回值有变化,不会替换原有函数,而是会建立新的函数。 SELECT调用可以指定不同参数来进行同名函数调用。语法CALL不支持调用不带有PACKAGE属性的同名函数。 在创建function时,不能在avg函数外面嵌套其他agg函数,或者其他系统函数。 在普通集群模式下,暂不支持将返回值、参数以及变量设置为建在非系统默认安装Node Group的表,sql function内部语句暂不支持对建在非系统默认安装Node Group的表操作。 新创建的函数默认会给PUBLIC授予执行权限(详见GRANT)。用户默认继承PUBLIC角色权限,因此其他用户也会有函数的执行权限并可以查看函数的定义,另外执行函数时还需要具备函数所在schema的USAGE权限。用户在创建函数时可以选择收回PUBLIC默认执行权限,然后根据需要将执行权限授予其他用户,为了避免出现新函数能被所有人访问的时间窗口,应在一个事务中创建函数并且设置函数执行权限。开启数据库对象隔离属性后,普通用户只能查看有权限执行的函数定义。 函数定义时如果指定为IMMUTABLE和SHIPPABLE类型,应该尽量避免函数中存在INSERT,UPDATE,DELETE,MERGE和DDL操作,因为上述操作应该由CN判断对应的执行节点,否则执行结果可能产生错误。如果在声明为IMMUTABLE和SHIPPABLE类型的函数中下推执行了DDL,可能会导致各节点数据库对象不一致。修复此类问题可以在CN上创建VOLATILE PL/SQL函数,函数定义中使用execute语句动态执行用于修复系统对象的DDL,再使用EXECUTE DIRECT ON语法在指定的DN上执行修复函数调用,从而解决引入的问题。 在函数内部调用其它无参数的函数时,可以省略括号,直接使用函数名进行调用。 在函数内部调用其他有出参的函数,如果在赋值表达式中调用时,被调函数的出参可以省略,给出了也会被忽略。 兼容Oracle风格的函数支持参数注释的查看与导出、导入。 兼容Oracle风格的函数支持介于IS/AS与plsql_body之间的注释的查看与导出、导入。 被授予CREATE ANY FUNCTION权限的用户,可以在用户模式下创建/替换函数。 函数默认为SECURITY INVOKER权限,如果想将默认行为改为SECURITY DEFINER权限,需要设置guc参数behavior_compat_options='plsql_security_definer'。 不支持形参仅在自定义ref cursor类型和sys_refcursor类型不同的重载。 带OUT模式参数的函数不支持嵌套调用,比如 b := func(a,func(c,1));,建议改为 tmp := func(c,1); b := func(a,tmp);。 如果将定义者权限的函数创建到其他用户SCHEMA下,则会以其他用户的权限执行该函数,有越权风险,请谨慎使用。
  • 语法格式 兼容PostgreSQL风格的创建自定义函数语法。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 CREATE [ OR REPLACE ] FUNCTION function_name ( [ { argname [ argmode ] argtype [ { DEFAULT | := | = } expression ]} [, ...] ] ) [ RETURNS rettype [ DETERMINISTIC ] | RETURNS TABLE ( { column_name column_type } [, ...] )] LANGUAGE lang_name [ {IMMUTABLE | STABLE | VOLATILE } | {SHIPPABLE | NOT SHIPPABLE} | WINDOW | [ NOT ] LEAKPROOF | {CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT } | {[ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER | AUTHID DEFINER | AUTHID CURRENT_USER} | {fenced | not fenced} | {PACKAGE} | COST execution_cost | ROWS result_rows | SET configuration_parameter { {TO | =} value | FROM CURRENT }} ][...] { AS 'definition' | AS 'obj_file', 'link_symbol' } 兼容Oracle风格的创建自定义函数的语法。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 CREATE [ OR REPLACE ] FUNCTION function_name ( [ { argname [ argmode ] argtype [ { DEFAULT | := | = } expression ] } [, ...] ] ) RETURN rettype [ DETERMINISTIC ] [ {IMMUTABLE | STABLE | VOLATILE } | {SHIPPABLE | NOT SHIPPABLE} | {PACKAGE} | {FENCED | NOT FENCED} | [ NOT ] LEAKPROOF | {CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT } | {[ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER | AUTHID DEFINER | AUTHID CURRENT_USER } | COST execution_cost | ROWS result_rows | SET configuration_parameter { {TO | =} value | FROM CURRENT | LANGUAGE lang_name ][...] { IS | AS } plsql_body /
  • DELETE 【规格】不支持DELETE语句中使用LIMIT。应使用WHERE条件明确需要更新的目标行。 【规格】在GTM-FREE模式下,不允许跨节点事务,因此删除HASH分布表中数据时,必须在WHERE条件中指定分布列等值过滤条件。 【规格】不支持多表删除。 多表删除即在单条SQL语句中,对多个表进行删除。 【规则】DELETE语句中必须有WHERE子句,避免全表扫描。 【规则】DELETE语句中禁止使用ORDER BY、GROUP BY子句,避免不必要的排序。 【规则】如果需要清空一张表,建议使用TRUNCATE,而不是DELETE。 TRUNCATE会创建新的物理文件,并在事务结束时将原文件物理删除,清空磁盘空间。而DELETE会将表中数据进行标记,直到VACUUM FULL阶段才会真正清理磁盘空间。 【建议】DELETE有主键或索引的表,WHERE条件应结合主键或索引,提高执行效率。 父主题: 数据库编程规范
  • JDBC 【关注】第三方工具通过JDBC连接GaussDB时,JDBC向GaussDB发起连接请求,会默认添加以下配置参数,详见JDBC代码ConnectionFactoryImpl类的实现。 params = { { "user", user }, { "database", database }, { "client_encoding", "UTF8" }, { "DateStyle", "ISO" }, { "extra_float_digits", "3" }, { "TimeZone", createPostgresTimeZone() }, }; 这些参数可能会导致JDBC客户端的行为与gsql客户端的行为不一致,例如,Date数据显示方式、浮点数精度表示、timezone显示。 如果实际期望和这些配置不符,建议在java连接设置代码中显式设定这些参数。 通过JDBC连接数据库时,会设置extra_float_digits=3,gsql中设置为extra_float_digits=0,可能会使同一条数据在JDBC显示和gsql显示的精度不同。 对于精度敏感的场景,建议使用numeric类型。 【规格】JDBC实例必须指定数据库,一旦实例创建,无法切换数据库。 【规格】单条SQL语句的长度不允许超过2G字节,业务应考虑通信成本,建议单条SQL语句不超过5K。 【规格】目前仅支持对CREATE/ALTER TABLE中列的DEFAULT值进行参数化设置,其他DDL使用Prepare Execute执行方式进行参数设置无效。 【规则】JDBC每条PreparedStatement语句中的参数不可超过32767个。 【规格】连接参数fetchsize必须要在autocommit关闭情况下使用,否则fetchsize配置无效。 【规则】使用默认GUC参数,避免通过JDBC发送SET请求修改GUC参数。参考GUC参数编程规范。 【规则】必须使用Prepare Execute方式执行查询语句,提高执行效率。 【规则】在同一个事务中,应逐条执行SQL语句,避免拼接多条SQL作为一条语句发送。参考【规则】通过JDBC接入数据库时,避免拼接多条SQL为一条语句发送执行。 【规则】JDBC客户端所在主机时区、数据库集群所在主机时区和集群配置过程中的时区,三者应保持一致。 【规则】如果在连接中创建了临时表,那么在将连接归还给连接池之前,必须将临时表删除,避免业务出错。 【建议】通过JDBC连接数据库时,应该保证以下三个时区设置一致: JDBC客户端所在主机的时区。 GaussDB集群所在主机的时区。 GaussDB集群配置过程中时区。 时区设置相关的操作,请联系管理员。 【建议】在JDBC向GaussDB申请连接的代码中,建议显式开启autocommit。如果基于性能或者其它方面考虑,需要关闭autocommit时,需要应用程序保证事务的提交。例如,在指定的业务SQL执行完之后做显式提交,特别是客户端退出之前务必保证所有的事务已经提交。 【建议】推荐使用连接池限制应用程序的连接数。不建议每执行一条SQL就连接一次数据库。 【建议】在应用程序完成作业任务之后,应当及时断开和GaussDB的连接,释放资源。建议在任务中设置session超时时间参数。 【建议】使用JDBC连接池,在将连接释放给连接池前,需要执行以下操作,重置会话环境。否则,可能会因为历史会话信息导致对象冲突。 如果在连接中设置了GUC参数,那么在将连接归还连接池之前,必须使用“SET SESSION AUTHORIZATION DEFAULT;RESET ALL;”将连接的状态清空。 如果使用了临时表,那么在将连接归还连接池之前,必须将临时表删除。 【建议】在不使用ETL工具,数据入库实时性要求比较高的情况下,建议在开发应用程序时,使用GaussDB JDBC驱动的copyManager接口进行微批导入。 【建议】合理设置prepareThreshold,如果query语句十分固定,建议设置为1。 【建议】建议设置连接参数autoBalance=true,开启CN负载均衡功能,并设置多个CN连接地址(使用逗号分隔)。 一旦开启autobalance,JDBC DRIVER会尝试将JDBC connection分配到不同的CN节点上。 设置多个CN连接地址的目的是JDBC DRIVER在首次获取集群CN列表时,避免因所设置的CN节点故障而失败。 一旦首次成功获取,便不会再依赖连接参数中指定的CN列表,而是根据实时获取的集群CN列表,每隔一段时间,选取连接其中有效的CN获取最新的CN列表。 【建议】建议设置连接参数batchMode=on,使用batch模式连接,提高执行性能。 【建议】应根据业务上层请求超时时间合理设置JDBC连接超时时间,避免作业完成或超长作业持续占用数据库资源。 超时参数包括loginTimeout、connectTimeout、socketTimeout等。 loginTimeout:Integer类型。指建立数据库连接的等待时间。超时时间单位为秒。默认值为0,表示已禁用,timeout不发生。 connectTimeout:Integer类型。用于连接服务器操作的超时值。如果连接到服务器花费的时间超过此值,则连接断开。超时时间单位为秒,默认值为0,表示已禁用,timeout不发生。 socketTimeout:Integer类型。用于socket读取操作的超时值。如果从服务器读取所花费的时间超过此值,则连接关闭。超时时间单位为秒,默认值为0,表示已禁用,timeout不发生。 cancelSignalTimeout:Integer类型。发送取消消息本身可能会阻塞,此属性控制用于取消命令的“connect超时”和“socket超时”。超时时间单位为秒,默认值为10秒。 tcpKeepAlive:Boolean类型。启用或禁用TCP保活探测功能。默认值为false。 父主题: 客户端编程规范
  • 获取驱动包 下载表1中的驱动包和驱动包校验包。 表1 驱动包下载列表 版本 下载地址 V2.0-2.x 驱动包 驱动包校验包 为了防止软件包在传递过程或存储期间被恶意篡改,下载软件包时需下载对应的校验包对软件包进行校验,校验方法如下: Linux操作系统软件包完整性校验: 上传软件包和软件包校验包到虚拟机的同一目录下。 执行如下命令,校验软件包完整性。 cat GaussDB_driver.zip.sha256 | sha256sum --check 如果回显OK,则校验通过。 GaussDB_driver.zip: OK Windows操作系统软件包完整性校验: 使用快捷键“Win+R”打开“运行”窗口。 在“打开”栏,输入“cmd”,按“Enter”回车,打开命令行页面。 执行以下命令,获取驱动包的Hash值。 certutil -hashfile {驱动包本地目录}\{驱动包名} sha256 {驱动包本地目录}:请根据实际下载目录进行替换。例如:C:\Users {驱动包名}:请根据实际下载的驱动包名进行替换。例如:GaussDB_driver.zip 示例:certutil -hashfile C:\Users\GaussDB_driver.zip sha256 将2获取到的Hash值和表1中获取到的驱动包校验包的Hash值进行比较。 若一致则通过校验。 若不一致,请重新下载驱动包,重复1~3进行校验。
  • 参数说明 nodename 节点名,对应在pgxc_node系统表的一行记录,指定后将修改记录中的nodeis_active字段值。 取值范围:字符串,只支持CN,并且要保证该节点名在pgxc_node系统表中有对应的记录。 status pgxc_node系统表中nodeis_active字段的更新值。 取值范围: - FALSE - TRUE nodename1[, nodename2, nodename3 ...] 该SQL执行的节点范围,ALTER COORDINATOR执行时会自动下发到范围内的所有节点,需要包含当前执行节点。 取值范围:字符串,只支持CN,要保证该节点名在pgxc_node系统表中有对应的记录,并且节点状态正常,否则SQL执行失败。
  • 示例 集群有3个CN,cn_5001、cn_5002、cn_5003,均处于正常工作状态。 cn_5001发生故障且满足剔除时间要求后,需要将cn_5001从集群中剔除,执行SQL在cn_5002和cn_5003节点上刷新pgxc_node系统表中cn_5001对应记录的nodeis_active为false: ALTER COORDINATOR cn_5001 SET False WITH (cn_5002,cn_5003); cn_5001故障解除后,为了在集群中加回cn_5001,执行SQL在cn_5002和cn_5003节点上刷新pgxc_node系统表中cn_5001对应记录的nodeis_active为true: ALTER COORDINATOR cn_5001 SET True WITH (cn_5002,cn_5003);
共100000条