人大金仓数据库KingbaseES支持的开发框架(基于JDBC)的介绍和使用之一之hibernate篇
1. 人大金仓数据库KingbaseES简介
1.1 数据库KingbaseES简介
人大金仓数据库管理系统 KingbaseES(KES,下文称) 是面向全行业、全客户关键应用的企业级大型通用数据库管理系统,适用于联机事务处理、查询密集型数据仓库、要求苛刻的互联网应用等场景,提供全部应用开发及系统管理功能,提供性能增强特性,可支持主备集群、读写分离集群、多活共享存储集群等全集群架构,具有高性能、高安全、高可用、易使用、易管理、易维护的特点,支持所有国内外主流CPU、操作系统与云平台部署。
1.2KES的客户端编程接口领域简介
KES客户端编程接口提供支持多种开发语言、多种接口和规范、多种开发框架、多个中间件和多种开发工具与KES服务端连接。
支持的情况具体如下:
项目 | 名称 |
语言 | Java |
C/C++,C# | |
JS | |
PHP | |
Python | |
Golang | |
Perl | |
Ruby | |
等 | |
接口 | JDBC |
ODBC | |
NDP(.NET) | |
OCI/DCI | |
OCCI | |
LIBKCI | |
等 | |
开发框架 | Hibernate(Java) |
Hibernate Spatial(Java) | |
Mybatis(Java) | |
Mybatis-Plus(Java) | |
Django(Python) | |
Nhibernate(.NET) | |
Entity Framework 6(.NET) | |
Entity Framework Core(.NET) | |
SQLAlchemy(Python) | |
QT | |
Activiti(Java) | |
Flyway(Java) | |
Liquibase(Java) | |
Dbunit(Java) | |
nacos(Java) | |
xxl-jobs(Java) | |
spring-cloud-starter-oauth2(Java) | |
liferay(Java) | |
jooq(Java) | |
Spring(Java) | |
Struts(Java) | |
Spring boot(Java) | |
flowable(Java) | |
druid(Java) | |
等 | |
中间件 | seata(分布式事务) |
mycat(分布式数据库中间件) | |
ShardingSphere(分布式数据库中间件) | |
等 | |
开发工具 | PowerBuilder |
Delphi | |
Kylix | |
JBuilder | |
visual studio | |
eclipse | |
等 |
1.3JDBC
1.3.1 JDBC简介
JDBC(Java DataBase Connectivity,java数据库连接)是一种用于执行SQL语句的Java API,可以为多种关系数据库提供统一访问,它由一组用Java语言编写的类和接口组成。JDBC提供了一种基准,据此可以构建更高级的工具和接口,使数据库开发人员能够编写数据库应用程序。
JDBC标准主要包含两个包java.sql和javax.sql。java.sql包含了核心的JDBC API,javax.sql包含了扩展的JDBC API。这两个包中的接口和类定义了所有的JDBC标准的对外接口,其具体定义可以查看JDK参考文档。
1.3.2JDBC基本流程
1.3.3KES的JDBC驱动使用说明
KingbaseES的版本支持兼容PG生态的数据库,提供了PG形态驱动,使用方式和PG生态数据库的使用方式一致。下以8.6版本提供安装包中的驱动包为例,具体如下:
驱动形态分类 | 驱动包名 | JDK版本 | 兼容生态 |
KES形态 | kingbase8-8.6.0.jar | 1.8以上 | KES生态数据库 |
kingbase8-8.6.0.jre7.jar | 1.7 | KES生态数据库 | |
kingbase8-8.6.0.jre6.jar | 1.6 | KES生态数据库 | |
PG形态 | postgresql-42.2.9.jar | 1.8以上 | PG生态数据库 |
postgresql-42.2.9.jre7.jar | 1.7 | PG生态数据库 | |
postgresql-42.2.9.jre6.jar | 1.6 | PG生态数据库 |
驱动形态使用对比:
驱动形态分类 | 加载方法 | URL |
KES形态 | Class.forName(“com.kingbase8.Driver”) | jdbc:kingbase8://localhost:54321/testdb |
PG形态 | Class.forName(“org.postgresql.Driver”) | jdbc:postgresql://localhost:54321/testdb |
1.3.4获取KES的JDBC驱动包
1、从人大金仓数据库安装包中获取。
2、从maven中央库获取。
加入以下配置:
- KES形态驱动包:
cn.com.kingbase
kingbase8
8.6.0
- PG形态驱动包:
cn.com.kingbase
postgresql-for-kingbase
8.6.0
2. KES支持的开发框架(基于JDBC)
2.1 ORM框架
ORM((Object Relational Mapping对象关系映射)框架是一种将数据库和对象之间进行映射的技术。它将数据库表的结构和数据映射到对象模型中,使开发人员可以使用面向对象的方式来操作数据库,而不需要直接编写SQL查询语句。
常用的框架有Hibernate和MyBatis等。
2.2基于JDBC的开发框架拓扑图
2.3KES支持的开发框架(基于JDBC)
从本文开始,我们将推出系列文章来介绍KES支持的开发框架使用,配置方式和简单用例实战及常见问题解决方法等。供读者参考。
KES支持的开发框架见如下表:
框架名称 | |
Hibernate | xxl-jobs |
Hibernate Spatial | spring-cloud-starter-oauth2 |
Mybatis | liferay |
Mybatis-Plus | jooq |
Activiti | Spring |
Flyway | Struts |
Liquibase | Spring boot |
Dbunit | flowable |
nacos | druid |
本文先介绍hibernate的环境配置,编程指南,注意事项和常见问题解决等。
3. KES与hibernate
3.1 Hibernate简介
Hibernate是一个开放源代码的对象关系映射框架,它对JDBC进行了非常轻量级的对象封装,它将POJO与数据库表建立映射关系,是一个全自动的ORM框架,Hibernate可以自动生成SQL语句,自动执行,使得Java程序员可以熟练地使用对象编程思维来操纵数据库。
3.2Hibernate支持的KES形态
框架名称 | 方言包 | 驱动形态 |
Hibernate | 提供 | KES、PG形态 |
3.3 Hibernate驱动包和方言包
KES提供了 Hibernate 的方言类 Kingbase8Dialect,目前KES共提供了以下几个方言包来支持Hibernate:
方言包 | 适用范围(hibernate版本) |
hibernate-2.0.dialect.jar | 2.0<=适用范围<2.1 |
hibernate-2.1.dialect.jar | 2.1<=适用范围<3.0 |
hibernate-3.0.dialect.jar | 3.0<=适用范围<3.0.3 |
hibernate-3.0.3.dialect.jar | 3.0.3<=适用范围<3.6.0 |
hibernate-3.6.dialect.jar | 3.6.0<=适用范围<4.0 |
hibernate-4.dialect.jar | 4.0<=适用范围<5.0 |
hibernate-5.dialect.jar | 5.0<=适用范围<6.0 |
hibernate-6.0.dialect.jar | 6.0<=适用范围 |
Kingbase8Dialect位于$KINGBASE_HOME/Interface/hibernate/目录中。 使用时将hibernatexxxdialect.jar导入到项目的Libraries中并定义相关配置项即可。
3.4Hibernate开发流程
hibernate首先通过配置文件cfg.xml初始化数据库,创建SessionFactory,进而得到session也就是一个数据库连接。 cfg文件中包括数据库驱动、URL、数据库名称以及密码等等参数,最重要的是将表或者视图的hbm文件写入cfg文件,否则是无法使用Hibernate服务的。 当用户操作数据库表或视图的时候,hibernate加载此表的hibernate mapping文件,也就是hbm.xml文件。hbm文件主要是映射数据库表与持久化类POJO。 通过hbm文件可以将实体对象与数据库表或者视图对应,从而间接的操作数据库表或者视图。
上图是Hibernate 使用原理图
3.5Hibernate 环境配置
本章描述如何配置Hibernate的开发环境,包括工程搭建、配置文件、配置方法和参数。
3.5.1Hibernate工程搭建
要使用Hibernate进行开发,需要先搭建环境。以下两种方法均可完成搭建环境:
创建好项目之后,在/lib 目录下导入hibernate的核心jar包以及hibernatexxxdialect.jar方言包。
使用Maven工具来管理jar包,修改pom.xml配置来导入hibernate核心jar包以及hibernatexxxdialect.jar方言包。
修改pom.xml配置内容如下:
cn.com.kingbase
KesDialect-for-hibernate2.0
1.0.0
cn.com.kingbase
KesDialect-for-hibernate2.1
1.0.0
cn.com.kingbase
KesDialect-for-hibernate3.0
1.0.0
cn.com.kingbase
KesDialect-for-hibernate3.0.3
1.0.0
cn.com.kingbase
KesDialect-for-hibernate3.6.0
1.0.0
cn.com.kingbase
KesDialect-for-hibernate4
1.0.0
3.5.2 Hibernate单独配置方式
定义 hibernate 配置文件,根据用户选择更改以下配置文件。
在hibernate.properties 中增加如下声明:
hibernate.dialect = org.hibernate.dialect.Kingbase8Dialect
在hibernate.cfg.xml 中增加如下声明:
org.hibernate.dialect.
Kingbase8Dialect
在persistence.xml 中增加如下声明:
<property name="hibernate.dialect"
value=”org.hibernate.dialect.Kingbase8Dialect” />
注意:hibernatexxxdialect.jar 方言包全部依赖于1.6以上版本JDK生成。
3.5.3Hibernate和Spring集成配置方式
Spring配置Hibernate方言包:
org.hibernate.dialect.Kingbase8Dialect
update
true
true
Spring-Boot配置Hibernate方言包:
spring.jpa.properties.hibernate.dialect = org.hibernate.dialect.Kingbase8Dialect
spring.jpa.hibernate.ddl-auto = update
spring.jpa.show-sql = true
3.5.4服务的配置方法和参数说明
Hibernate配置文件示例:
<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate
Configuration DTD 3.0//EN”
“http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd”>
create-drop
true
false
org.hibernate.dialect.Kingbase8Dialect
com.kingbase8.Driver
jdbc:kingbase8://localhost:54321/
test
test
test
配置时按照实际使用情况修改 “dialect” 、 “connection.driver_class” 等参数。
3.6Hibernate编程指南
本章节列举了部分使用Hibernate进行的开发程序示例。
3.6.1 Hibernate映射文件示例
下例程序为Hibernate的映射文件配置:
<!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping
DTD 3.0//EN”
“http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd”>
3.6.2Hibernate的java对象示例
下例为Hibernate的Java对象示例:
package hibernate_test;
public class TestDb {
private String username;
private Long id;
private boolean btest;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String myname) {
this.username = myname;
}
public boolean getBtest() {
return btest;
}
public void setBtest(boolean bbtest) {
this.btest = bbtest;
}
}
3.6.3 Hibernate的java使用示例
下例为Hibernate的Java使用示例
/* 定义参数 */
String name = “username”;
Long id = 0;
boolean btest = false;
/* 连接 DB */
SessionFactory sessionFactory = new Configuration().configure()
.buildSessionFactory();
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();
/* 新建一行数据插入 hibernate_test表 */
TestDb user = new TestDb();
user.setUsername(name);
user.setId(id);
user.setBtest(btest);
session.save(user);
/* 从hibernate_test表中查询数据 */
TestDb obj = (TestDb) session.load(TestDb.class, new Long(id));
System.out.println(obj.getUsername());
/* 更新数据 */
tx = session.beginTransaction();
obj = (TestDb) session.load(TestDb.class, new Long(id));
obj.setUsername(“update_test” + id);
session.update(obj);
tx.commit();
3.7Hibernate注意事项
- HQL(JPA QL)不支持KingbaseES特有的函数,包括:TO_HEX、UNICODE、SETSEED、STRPOS、GET_BIT、GET_BYTE、SET_BIT、SET_BYTE、EMPTY_BLOB、EMPTY_CLOB、CAST、ARRAY_NDIMS、ARRAY_FILL、UNNEST和ARRAY_LENGTH等。
- HQL(JPA QL)不支持某些操作符,包括:+、^、%、&、|、||、#和~等,以及UNION、UNION ALL、INTERSECT、EXCEPT。
- 不支持INTERVAL数据类型以及返回值为INTERVAL的系统函数,包括:AGE、DATE_FORMAT、ISFINITE、STR_VALID和TIMEOFDAY。
- 对于近义的系统函数,只支持常用的名称,例如:sqrt(dsqrt)、cbrt(dcbrt)等。
- 对于重载的系统函数,只支持常用的参数及返回值类型,例如:LEFT(expr1 TEXT, expr2 INTEGER)、REPLICATE(expr1 TEXT, expr2 INTEGER)、RIGHT(expr1 TEXT, expr2 INTEGER)和SUBSTRING(expr1 TEXT, [FROM] expr2 INTEGER[,[FOR] expr3 INTEGER])等。
- 使用原生查询时,某些函数的返回值与KingbaseES有差异,例如:SIGN()应返回整型值但实际返回浮点型。
- 只有在查询时才可使用Query.getSingleResult() 方法,例如因为该方法会添加Limit子句,call function() 执行函数取返回值时使用该方法会构造一个不合法的SQL语句。
- 3.0.3和4两个版本的方言包中还包含一个名称为KingbaseBooleanDialect的方言包,该方言包用于hibernate使用Java的boolean类型映射数据库的numeric类型且使用hibernate默认的BooleanType时,hibernate执行操作可以将hql中boolean类型的true或者false转换成1或者0。 如:HQL语句 select p.name FROM Person p where p.sex=true 会转换为SQL语句 select person0_.name as col_0_0_ from person person0_ where person0_.sex=1 。
3.8常见问题
- Springboot JPA配置方言包问题
org.springframework.beans.factory.BeanCreationException:Errorcreatingbeanwithname’entityManagerFactory’definedinclasspathresource
Causedby:org.hibernate.HibernateException:AccesstoDialectResolutionInfocannotbenullwhen’hibernate.dialect’notset
HibernateSQL方言没有设置导致的,在properties文件中增加下面这行:
spring.jpa.database-platform=org.hibernate.dialect.Kingbase8Dialect或者
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.Kingbase8Dialect
- Hibernate控制输出真实SQL日志
编辑hibernate.cfg.xml,配置方法:
1、参数:show_sql=true 打印SQL语句;
2、参数:format_sql=true 使SQL语句格式更加美观统一;
3、参数:use_sql_comments=true 使SQL语句中自动注入注释,增加可读性。
true //控制台打印SQL语句
true //格式化SQL语句
true //指出是什么操作生成了该语句
- 表取名user怎么规避?
在映射上@Table(name=“t_user”)换个名字或者@Table(name=”user”,schema=”xxx”)显示指定模式名。
- Hibernate的hq不支持部分数据库函数的使用
1.将hql语句转换为sql语句,createQuery使用的是hql,createSQLQuery使用的是sql语句;
2.在方言包里注册函数解决。
- V8 Hibernate非法ong值问题
这个问题是由于V8 hibernate把TEXT类型默认对应到CLOB类型处理,但是CLOB是通过OID来访问的,所以造成类型转换报错。解决办法更换新的方言包,新的dialect。
- Hibernate 无法确定参数类型$1
1.使用cast函数对于不识别的类型进行强转,如cast(? as timestamp),as后面的类型需要为hibernate类型,hibernate类型自行百度。
2.对于V7,这个问题可能是用户打开了Hibernate的SQL注释功能,改为false即可。
false
parse JDBC_STATEMENT_7: /* from TestDb where username=$1 */ select testdb0_.id as id0_, testdb0_.username as username0_, testdb0_.btest as btest0_ from hibernate_test testdb0_ where testdb0_.username=$2
ERROR: could not determine data type of parameter $1
- Hibernate 错误: 字段的类型为 TEXT, 但表达式的类型为 BYTEA你需要重写或转换表达式
这个问题原因是JDBC指定了bytea的OID传给服务器,而服务器实际字段类型是TEXT,不支持类型转换。
查看hibernate源码:
public Query setParameter(int position, Object val) throws HibernateException {
if (val == null) {
setParameter( position, val, Hibernate.SERIALIZABLE );
}
}
看出对于null值,hibernate都是按照Hibernate.SERIALIZABLE类型处理。而Hibernate.SERIALIZABLE类型使用Hibernate.BINARY.set(st, toBytes(value), index)。
Hibernate.BINRAY底层使用JDBC的setBinaryStream或者setBytes绑定参数。
解决办法:JDBC直接修改所有Bind参数传bytea的地方都改成0。如仍需绑定为bytea,可通过连接参数bytestype=bytea来指定。
- Hibernate设置为update已经建好表,仍旧去建表
原因为使用了大小写不敏感的数据库,在大小写不敏感的库中,查询返回的表名与建表时的大小写保持一致。如果建表时使用小写,Hibernate查询返回的表名为小写,本地的表名是转为大写去比较,找不到所以会去建表,请改为大小写敏感的数据库。
修改后可能存在的问题:
1.索引重复创建
应用可能是从MySQL、SQLServer迁移过来的。索引名称在某些数据库中(如 MySQL、SQLServer),索引是以表为维度创建的,在不同的表中的索引是可以重名的; 而在另外的一些数据库中(如 PostgreSQL、Oracle、KingbaseES),索引是以数据库为维度创建的,即使是作用在不同表上的索引,它们也要求其名称的唯一性。所以需要修改索引名称。
- 控制台报错
java.lang.NoSuchMethodError: javax.persistence.Table.indexes()[Ljavax/persistence/Index;
jar包冲突,有多个jar包存在javax/persistence/Index类。