Help Center/ GaussDB/ Developer Guide(Distributed_V2.0-3.x)/ Application Development Guide/ Development Based on JDBC/ Development Process/ Connecting to a Database/ Connecting to a Database in Non-Encrypted Mode
Updated on 2025-03-13 GMT+08:00
View PDF
Share

Connecting to a Database in Non-Encrypted Mode

To connect to a database in non-encrypted mode, you need to load a driver and then establish a database connection. This section describes methods of loading drivers, APIs for creating database connections, and APIs for non-encrypted connections.

Methods of Loading Drivers

You can use either of the following methods to load the driver (opengaussjdbc.jar is used as an example):
  • Load a driver at any position in code before creating a connection. 
    Class.forName("com.huawei.opengauss.jdbc.Driver");
  • Specify the driver name when a JVM is started. This parameter is used to execute Java code in the DOS window or on Linux. jdbctest is the name of a test application. 
    java -Djdbc.drivers=com.huawei.opengauss.jdbc.Driver jdbctest;
    • If gsjdbc4.jar is used, change the driver class name to org.postgresql.Driver.
    • GaussDB is compatible with PG in the use of JDBC. Therefore, when two JDBC drivers are used in the same process, class names may conflict.
    • JDBC of this version does not support identity & access management suite (IAM) for authentication.
    • Compared with the PG driver, the GaussDB JDBC driver has the following enhanced features:
      • SHA-256 is supported for encrypted login.
      • The third-party log framework that implements the sf4j API can be connected.
      • Distributed load balancing at the connection level is supported.
      • DR failover is supported.

APIs for Creating Database Connections

JDBC provides three APIs for creating database connections. For details about the url, info, user, and password parameters, see Table 1.

API 1: DriverManager.getConnection(String url). You need to write a database username and password in a URL, which is insecure and not recommended.

API 2: DriverManager.getConnection(String url, String user, String password). For details, see Connecting to a Database Using API 2.

API 3: DriverManager.getConnection(String url, Properties info). For details, see Connecting to a Database Using API 3.

Table 1 Database connection parameters

Parameter

Description

url

Database connection descriptor when opengaussjdbc.jar is used. The format is as follows:

  • jdbc:opengauss:
  • jdbc:opengauss:database
  • jdbc:opengauss://host/database
  • jdbc:opengauss://host:port/database
  • jdbc:opengauss://host:port/database?param1=value1&param2=value2
  • jdbc:opengauss://host1:port1,host2:port2/database?param1=value1&param2=value2
NOTE:
  • If gsjdbc200.jar is used, replace jdbc:opengauss with jdbc:gaussdb.
  • database indicates the name of the database to connect. The database name is the same as the username by default.
  • host indicates the name or IP address of the database server.

    For security reasons, the database CN prevents unauthorized access from other nodes within the cluster. To access the CN from inside the cluster, deploy the JDBC program on the host where the CN is located and set host to 127.0.0.1. Otherwise, the error message "FATAL: Forbid remote connection with trust method!" may be displayed.

    It is recommended that the service system be deployed outside the cluster. Otherwise, the database performance may be affected.

    By default, the localhost is used to connect to the server.

  • port indicates the port number of the database server.

    By default, the database on port 5431 of the localhost is connected.

  • param indicates a database connection attribute. Parameters can be configured in the URL. The URL starts with a question mark (?), uses an equal sign (=) to assign values to parameters, and uses ampersands (&) to separate parameters.
  • value indicates the database connection attribute values.
  • The connectTimeout and socketTimeout parameters must be set for connection. If they are not set, the default value 0 is used, indicating that the connection will not time out. When the network between a DN and the client is faulty, the client cannot receive the ACK packet from the DN and retries transmission repeatedly. A timeout error is reported only when the number of retransmission times reaches 15 (the default value). As a result, the RTO is high.
  • You are advised to ensure the validity of the URL when using the standard JDBC API to establish a connection. Otherwise, connection may fail. If the error information contains the original URL character string, it may cause sensitive information leakage.
  • Sensitive information such as passwords and credentials cannot be configured in URLs. You are advised to configure sensitive information using connection properties. For details, see Connecting to a Database Using API 3.

info

Database connection property. For details about all parameters, see Connection Parameter Reference.

user

Database user.

password

Password of the database user.

Connecting to a Database Using API 2

The following uses opengaussjdbc.jar as an example to describe how to use the DriverManager.getConnection(String url, String user, String password) API to establish a database connection. The procedure is as follows:

  1. Import java.sql.Connection and java.sql.DriverManager.

    java.sql.Connection is a database connection API. The getConnection() method of java.sql.DriverManager is used to connect applications to a database. In addition, you need to import other APIs and classes based on the actual application scenario. For details, see JDBC Interface Reference. 
    1
2
    		 
    import java.sql.Connection;
import java.sql.DriverManager;

  2. Specify the database sourceURL (change $ip, $port, and database as required), username, and password.

    Writing the username and password to code has great security risks. You are advised to store the username and password in environment variables. 
    String sourceURL = "jdbc:opengauss://$ip:$port/database";
String userName = System.getenv("EXAMPLE_USERNAME_ENV");
String password = System.getenv("EXAMPLE_PASSWORD_ENV");

  3. Load the driver.

    1. Add the opengaussjdbc.jar package to the code running tool (such as IDE).
    2. Load the database driver com.huawei.opengauss.jdbc.Driver as follows: 
      String driver = "com.huawei.opengauss.jdbc.Driver";
Class.forName(driver);

  4. Establish a database connection.

    Call DriverManager.getConnection(String url, String user, String password) to connect to the database. 
    Connection conn = DriverManager.getConnection(sourceURL, userName, password);

Connecting to a Database Using API 3

The following uses opengaussjdbc.jar as an example to describe how to use the DriverManager.getConnection(String url, Properties info) API to establish a database connection. The procedure is as follows:

  1. Import java.sql.Connection, java.sql.DriverManager, and java.util.Properties.

    The setProperty() method of java.util.Properties is used to set attribute values of the Properties object. In addition, you need to import other APIs and classes based on the actual application scenario. For details, see JDBC Interface Reference. 
    1
2
3
    		 
    import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;

  2. Specify the database sourceURL (change $ip, $port, and database as required), username, and password.

    Writing the username and password to code has great security risks. You are advised to store the username and password in environment variables. 
    String sourceURL = "jdbc:opengauss://$ip:$port/database";
String userName = System.getenv("EXAMPLE_USERNAME_ENV");
String password = System.getenv("EXAMPLE_PASSWORD_ENV");

  3. Create a Properties object and set userName and password as the attribute values of the object. 

    Properties info = new Properties();
info.setProperty("user", userName);
info.setProperty("password", password);

  4. Load the driver.

    1. Add the opengaussjdbc.jar package to the code running tool (such as IDE).
    2. Load the database driver com.huawei.opengauss.jdbc.Driver as follows:
    String driver = "com.huawei.opengauss.jdbc.Driver";
Class.forName(driver);

  5. Establish a database connection.

    Call DriverManager.getConnection(String url, Properties info) to connect to the database. 
    1
    		 
    Connection conn = DriverManager.getConnection(sourceURL, info);

Parent topic: Connecting to a Database