What is openGauss-connector-jdbc

openGauss is an open source relational database management system. It has multi-core high-performance, full link security, intelligent operation and maintenance for enterprise features. openGauss, which is early originated from PostgreSQL, integrates Huawei's core experience in database field for many years. It optimizes the architecture, transaction, storage engine, optimizer and ARM architecture. At the meantime, openGauss as a global database open source community, aims to further advance the development and enrichment of the database software/hardware application ecosystem.

Java Database Connectivity (JDBC) is an application programming interface (API) for the programming language Java, which defines how a client may access a database. It is a Java-based data access technology used for Java database connectivity. It provides methods to query and update data in a database, and is oriented toward relational databases. openGauss-connector-jdbc is to provide users with access to the database through the Java language application interface . Users can use the jar package provided by the openGauss official website (refer to the Direct Access section) or build their own jar package (refer to the Building from Source section to operate the database using JDBC.

Direct access

Before using the openGauss JDBC driver, make sure your server is up and running with the openGauss database (refer to the openGauss Quickstart）。

Get from maven central repository

Java developers can get jar packages directly from the maven central repository with the following coordinates:

<groupId>org.opengauss</groupId>
<artifactId>opengauss-jdbc</artifactId>

Get from the community website

1. Download the installation package from the official website.

   Click on link and under the openGauss Connectors section, select the download button for JDBC_${version} according to the corresponding system of the server where you are deploying the database. ${version} is the version number you need.

2. Decompress the zip file.

   tar -zxvf openGauss-${version}-JDBC.tar.gz
   

3. After unpacking, you can see two jar packages in the same directory, opengauss-jdbc-${version}.jar and postgresql.jar. opengauss-jdbc-${version}.jar is a package that can coexist with PG-JDBC, the package name is changed from 2.0.1 to org.postgresql.jar. postgresql to org.opengauss, and the driver name is replaced from jdbc:postgresql:// to jdbc:opengauss://. This is the same package that is currently available from the maven central repository.

INSTALLING THE DRIVER

To install the driver, the postgresql.jar file has to be in the classpath.

ie: under LINUX/SOLARIS (the example here is my linux box):

export CLASSPATH=.:/usr/local/pgsql/share/java/postgresql.jar

or

export CLASSPATH=.:/usr/local/pgsql/share/java/opengauss-jdbc-${version}.jar

Build from Source

Overview

The openGauss JDBC driver currently offers 3 ways to build. One is to build via the one-click script build.sh. The second is a step-by-step build via script. The third is to build via the mvn command.

This will compile the correct driver for your JVM, and build a .jar file (Java ARchive) called postgresql.jar and opengauss-jdbc--${version}.jar in output/, and you can get openGauss-${version}-jdbc.tar.gz too.

Notice: postgresql.jar is conflict use with postgres database. Because all class was in package org.postgresql. opengauss-jdbc-${version}.jar is compatibility with postgres database, all java package renamed org.opengauss, and jdbc driver is: jdbc:opengauss:/

Remember: Once you have compiled the driver, it will work on ALL platforms that support that version of the API. You don't need to build it for each platform.

OS and Software Dependency Requirements

The openGauss JDBC driver is generated to support the following operating systems:

• CentOS 7.6（x86 architecture）
• openEuler-20.03-LTS（aarch64 architecture）
• Windows

The following table lists the software requirements for compiling the openGauss-connector-jdbc.

You are advised to use the default installation packages of the following dependent software in the listed OS installation CD-ROMs or sources. If the following software does not exist, refer to the recommended versions of the software.

Software dependency requirements are as follows:

Software and Environment Requirements	Recommended Version
maven	3.6.1
java	1.8
Git Bash (Windows)	-
zip/unzip (Windows)	-

Downloading openGauss-connector-jdbc

You can download openGauss-connector-jdbc from open source community.

git clone https://gitee.com/opengauss/openGauss-connector-jdbc.git

Now we have completed openGauss-connector-jdbc code. For example, we store it in following directories.

• /sda/openGauss-connector-jdbc

Compiling Third-Party Software（optional）

Before building openGauss-connector-jdbc, you need to compile the open source and third-party software that openGauss depends on. We already provide compiled open source and third-party software in open_source under the openGauss-connector-jdbc directory, so you can skip that part by using the open_source we provide directly. These open source and third party software are stored in the openGauss-third_party code repository and usually only need to be built once. If there are updates to the open source software, the software needs to be rebuilt.

You can also get the output files of open source software compilations and builds directly from the binarylibs library.

If you want to compile your own third-party software, please go to the openGauss-third_party repository for details.

After executing the above script, the final compile and build results are stored in the binarylibs directory at the same level as openGauss-third_party. These files will be used when compiling openGauss-connector-jdbc.

Compiling

Getting jar packages with one-click scripting (Linux)

The build.sh in the openGauss-connector-jdbc directory is an important scripting tool for the compilation process. This tool allows for quick code compilation and packaging.

See the table below for a description of the parameters.

Option	Default Value	Parameter	Description
-3rd	${Code directory}/binarylibs	[binarylibs path]	Specifies the path of binarylibs. It is recommended to specify the path as open_source/ or /sda/openGauss-connector-jdbc/open_source/. If you have your own compiled third-party libraries that openGauss depends on, you can also specify the path of compiled third-party libraries, such as /sda/binarylibs.

Now you know the usage of build.sh, so you can compile the openGauss-connector-jdbc by one command with build.sh. In build.sh, maven and java8 will be installed automatically and use to build target.

1. Execute the following command to get to the code directory:

   [user@linux sda]$ cd /sda/openGauss-connector-jdbc
   

2. Execute the following command to package using build.sh:

   [user@linux openGauss-connector-jdbc]$ sh build.sh -3rd open_source/ 
   

   When finished, the following will be displayed to indicate successful packaging:

   Successfully make postgresql.jar
   opengauss-jdbc-${version}.jar
   postgresql.jar
   Successfully make jdbc jar package
   now, all packages has finished!
   

   After successful compilation, two jar packages will appear, opengauss-jdbc-${version}.jar and postgresql.jar. compiled jar package path is:/sda/openGauss-connector-jdbc/output.

Getting jar packages with one-click scripting (Windows)

1. Prepare the Java and Maven environments, and the zip/unzip commands that can be used in Git Bash.

2. Execute the following command to get to the code directory:

   [user@linux openGauss-connector-jdbc]$ cd /sda/openGauss-connector-jdbc
   

3. Run the script build_on_windows_git.sh:

   [user@linux openGauss-connector-jdbc]$ sh build_on_windows_git.sh
   

   Run the script build_on_windows_git.sh:

   begin run
   Successfully make postgresql.jar package in /sda/openGauss-connector-jdbc/output/postgresql.jar
   Successfully make opengauss-jdbc jar package in /sda/openGauss-connector-jdbc/output/opengauss-jdbc-${version}.jar
   Successfully make jdbc jar package in /sda/openGauss-connector-jdbc/openGauss-${version}-JDBC.tar.gz
   

   After successful compilation, two jar packages will appear, opengauss-jdbc-${version}.jar and postgresql.jar. the compiled jar package path is /sda/openGauss-connector-jdbc/output/. There will also be a zip archive of these two jar packages, openGauss-${version}-JDBC.tar.gz, with the path /sda/openGauss-connector-jdbc/.

Getting jar packages using the mvn command (Windows or Linux)

1. Prepare the Java and Maven environments, and for Windows, the zip/unzip commands that can be used in Git Bash.

2. Execute the following command to get to the code directory：

   [user@linux sda]$ cd /sda/openGauss-connector-jdbc
   

3. Preparing scripts with demos：

   [user@linux openGauss-connector-jdbc]$ sh prepare_demo.sh
   

4. Modify the pom.xml in the root directory：

   Change the module from jdbc to pgjdbc, as shown below:

   <modules>
     <module>pgjdbc</module>
   </modules>
   

5. Execute the mvn command:

   [user@linux openGauss-connector-jdbc]$ mvn clean install -Dmaven.test.skip=true
   

   A successful build on a Linux system will display the following result:

   [INFO] Reactor Summary:
   [INFO] 
   [INFO] openGauss JDBC Driver ............................. SUCCESS [5.344s]
   [INFO] PostgreSQL JDBC Driver aggregate .................. SUCCESS [0.004s]
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 5.439s
   [INFO] Finished at: Tue Aug 31 21:55:01 EDT 2021
   [INFO] Final Memory: 44M/1763M
   [INFO] ------------------------------------------------------------------------
   

   Two jar packages will appear after a successful build, opengauss-jdbc-${version}.jar and original-opengauss-jdbc-${version}.jar. jar package path is /sda/openGauss-connector-jdbc/pgjdbc /target/.

Using JDBC

Reference JDBC-based development.

Docs

For more details about the installation guide, tutorials, and APIs, please see the User Documentation.

Community

Governance

Check out how openGauss implements open governance works.

Communication

• WeLink- Communication platform for developers.
• IRC channel at #opengauss-meeting (only for meeting minutes logging purpose)
• Mailing-list: https://opengauss.org/en/community/onlineCommunication.html

Contribution

Welcome contributions. See our Contributor for more details.

Release Notes

For the release notes, see our RELEASE.

License

MulanPSL-2.0