Connecting to a Database

After a database is connected, you can execute SQL statements in the database.

Note

If you use an open-source Java Database Connectivity (JDBC) driver, ensure that the database parameter password_encryption_type is set to 1. If the value is not 1, the connection may fail. A typical error message is "none of the server's SASL authentication mechanisms are supported." To avoid such problems, perform the following operations:

  1. Set password_encryption_type to 1. For details, see "Modifying Database Parameters" in User Guide.

  2. Create a new database user for connection or reset the password of the existing database user.

    • If you use an administrator account, reset the password. For details, see "Password Reset" in User Guide.

    • If you are a common user, use another client tool (such as Data Studio) to connect to the database and run the ALTER USER statement to change your password.

  3. Connect to the database.

Here are the reasons why you need to perform these operations:

  • MD5 algorithms may by vulnerable to collision attacks and cannot be used for password verification. Currently, GaussDB(DWS) uses the default security design. By default, MD5 password verification is disabled, but MD5 is required by the open-source libpq communication protocol of PostgreSQL. For connectivity purposes, you need to adjust the cryptographic algorithm parameter password_encryption_type and enable the MD5 algorithm.

  • The database stores the hash digest of passwords instead of password text. During password verification, the system compares the hash digest with the password digest sent from the client (salt operations are involved). If you change your cryptographic algorithm policy, the database cannot generate a new MD5 hash digest for your existing password. For connectivity purposes, you must manually change your password or create a new user. The new password will be encrypted using the hash algorithm and stored for authentication in the next connection.

Function Prototype

JDBC provides the following three database connection methods:

  • DriverManager.getConnection(String url);

  • DriverManager.getConnection(String url, Properties info);

  • DriverManager.getConnection(String url, String user, String password);

Parameter

Table 1 Database connection parameters

Parameter

Description

url

gsjdbc4.jar database connection descriptor. The descriptor format can be:

Note

If gsjdbc200.jar is used, replace jdbc:postgresql with jdbc:gaussdb.

  • database: indicates the name of the database to be connected.

  • host: indicates the name or IP address of the database server.

    Specify the IP address for connecting to the GaussDB(DWS) cluster on GaussDB(DWS) management console. If the connected host and the GaussDB(DWS) cluster are in the same network, select the private IP address. Otherwise, select the public IP address.

    For security purposes, the CN forbids access from other nodes in the cluster without authentication. 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.

  • port: indicates the port number of a database server. By default, the database on port 8000 of the local host is connected.

  • Multiple IP addresses and ports can be configured. JDBC balances load by random access and failover, and will automatically ignore unreachable IP addresses.

    IP addresses are separated using commas. Example: jdbc:postgresql://10.10.0.13:8000,10.10.0.14:8000/database

info

Database connection properties. Common properties include:

  • user: string type. It indicates the database user who creates the connection.

  • password: string type. It indicates the password of a database user.

  • ssl: boolean type. It indicates whether the Secure Socket Layer (SSL) is used.

  • loggerLevel: string type. It indicates the amount of information that the driver logs and prints to the LogStream or LogWriter specified in the DriverManager. Currently, OFF, DEBUG, and TRACE are supported. DEBUG indicates that only logs of the DEBUG or higher level are printed, generating little log information. TRACE indicates that logs of the DEBUG and TRACE levels are printed, generating detailed log information. The default value is OFF, indicating that no information will be logged.

  • prepareThreshold: integer type. It indicates the number of PreparedStatement executions required before requests are converted to prepared statements in servers. The default value is 5.

  • batchMode: boolean type. It indicates whether to connect the database in batch mode.

  • fetchsize: integer type. It indicates the default fetch size for statements in the created connection.

  • ApplicationName: string type. It indicates an application name. The default value is PostgreSQL JDBC Driver.

  • allowReadOnly: boolean type. It indicates whether to enable the read-only mode for connection. The default value is false. If the value is not changed to true, the execution of connection.setReadOnly does not take effect.

  • blobMode: string type. It is used to set the setBinaryStream method to assign values to different data types. The value on indicates that values are assigned to the BLOB data type and off indicates that values are assigned to the BYTEA data type. The default value is on.

  • connectionExtraInfo: boolean type. It indicates whether the JDBC driver reports the driver deployment path and process owner to the database.

    Note

    The value can be true or false. The default value is false. If connectionExtraInfo is set to true, the JDBC driver reports the driver deployment path and process owner to the database and displays the information in the connection_info parameter (see connection_info). In this case, you can query the information from PG_STAT_ACTIVITY or PGXC_STAT_ACTIVITY.

user

Indicates a database user.

password

Indicates the password of a database user.

Examples

//gsjdbc4.jar is used as an example.
//The following code encapsulates database connection operations into an interface. The database can then be connected using an authorized username and password.

public static Connection GetConnection(String username, String passwd)
    {
        //Set the driver class.
        String driver = "org.postgresql.Driver";
        //Set the database connection descriptor.
        String sourceURL = "jdbc:postgresql://10.10.0.13:8000/postgres?currentSchema=test";
        Connection conn = null;

        try
        {
            //Load the driver.
            Class.forName(driver);
        }
        catch( Exception e )
        {
            e.printStackTrace();
            return null;
        }

        try
        {
             //Create a connection.
            conn = DriverManager.getConnection(sourceURL, username, passwd);
            System.out.println("Connection succeed!");
        }
        catch(Exception e)
        {
            e.printStackTrace();
            return null;
        }

        return conn;
    };