PolarDB：JDBC

Konfigurasi driver JDBC

Sebelum menggunakan driver JDBC dalam aplikasi Java, Anda harus menambahkan path paket driver JDBC ke CLASSPATH. Misalnya, jika driver JDBC berada di path /usr/local/polardb/share/java/, jalankan perintah berikut untuk menambahkan path tersebut ke CLASSPATH:

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/<jar_package_name.jar>

Contoh:

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/polardb-jdbc18.jar

Jalankan perintah berikut untuk melihat versi JDBC saat ini:

#java -jar <jar_package_name.jar>

Contoh:

#java -jar polardb-jdbc18.jar
POLARDB JDBC Driver 42.2.XX.XX.0

Hubungkan ke PolarDB

• Example

  package com.aliyun.polardb;
  
  import java.sql.Connection;
  import java.sql.Driver;
  import java.sql.DriverManager;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.sql.Statement;
  import java.util.Properties;
  
  /**
   * POLARDB JDBC DEMO
   * <p>
   * Pastikan alamat IP host yang menjalankan demo ini berada dalam daftar putih kluster Anda.
   */
  public class PolarDBJdbcDemo {
    /**
     * Ganti informasi berikut.
     */
    private final String host = "***.o.polardb.rds.aliyuncs.com";
    private final String user = "***";
    private final String password = "***";
    private final String port = "1521";
    private final String database = "db_name";
  
    public void run() throws Exception {
      Connection connect = null;
      Statement statement = null;
      ResultSet resultSet = null;
  
      try {
        Class.forName("com.aliyun.polardb.Driver");
  
        Properties props = new Properties();
        props.put("user", user);
        props.put("password", password);
        String url = "jdbc:polardb://" + host + ":" + port + "/" + database;
        connect = DriverManager.getConnection(url, props);
  
        /**
         * create table foo(id int, name varchar(20));
         */
        String sql = "select id, name from foo";
        statement = connect.createStatement();
        resultSet = statement.executeQuery(sql);
        while (resultSet.next()) {
          System.out.println("id:" + resultSet.getInt(1));
          System.out.println("name:" + resultSet.getString(2));
        }
      } catch (Exception e) {
        e.printStackTrace();
        throw e;
      } finally {
        try {
          if (resultSet != null)
            resultSet.close();
          if (statement != null)
            statement.close();
          if (connect != null)
            connect.close();
        } catch (SQLException e) {
          e.printStackTrace();
          throw e;
        }
      }
    }
  
    public static void main(String[] args) throws Exception {
      PolarDBJdbcDemo demo = new PolarDBJdbcDemo();
      demo.run();
    }
  }

• Load the JDBC driver

  Dalam aplikasi Anda, jalankan perintah berikut untuk memuat driver JDBC:

  Class.forName("com.aliyun.polardb.Driver");

• Connect to a database

  Dalam JDBC, database biasanya direpresentasikan oleh URL. Berikut adalah contohnya.

  jdbc:polardb://pc-***.o.polardb.rds.aliyuncs.com:1521/polardb_test?user=test&password=Pw123456

  Parameter	Contoh	Deskripsi
  Prefiks URL	jdbc:polardb://	Awalan untuk URL yang digunakan untuk menghubungkan ke PolarDB adalah jdbc:polardb://.
  Titik akhir	pc-***.o.polardb.rds.aliyuncs.com	Titik akhir kluster PolarDB. Untuk informasi selengkapnya, lihat Lihat atau minta titik akhir.
  Port	1521	Port kluster PolarDB. Port default-nya adalah 1521.
  Database	polardb_test	Nama database yang ingin Anda hubungkan.
  Nama pengguna	test	Username kluster PolarDB.
  Kata sandi	Pw123456	Password yang sesuai dengan username kluster PolarDB.

• Query data and process the results

  Saat mengakses database untuk menjalankan kueri, buat objek Statement, PreparedStatement, atau CallableStatement.

  Contoh sebelumnya menggunakan objek Statement. Contoh berikut menunjukkan cara menggunakan objek PreparedStatement:

  PreparedStatement st = conn.prepareStatement("select id, name from foo where id > ?");
  st.setInt(1, 10);
  resultSet = st.executeQuery();
  while (resultSet.next()) {
      System.out.println("id:" + resultSet.getInt(1));
      System.out.println("name:" + resultSet.getString(2));
  }

  Anda dapat menggunakan objek CallableStatement untuk memproses prosedur tersimpan. Berikut adalah contohnya:

  String sql = "{?=call getName (?, ?, ?)}";
  CallableStatement stmt = conn.prepareCall(sql);
  stmt.registerOutParameter(1, java.sql.Types.INTEGER);
  
  //Bind IN parameter first, then bind OUT parameter
  int id = 100;
  stmt.setInt(2, id); // This would set ID as 102
  stmt.registerOutParameter(3, java.sql.Types.VARCHAR);
  stmt.registerOutParameter(4, java.sql.Types.INTEGER);
  
  //Use execute method to run stored procedure.
  stmt.execute();
  
  //Retrieve name with getXXX method
  String name = stmt.getString(3);
  Integer msgId = stmt.getInt(4);
  Integer result = stmt.getInt(1);
  System.out.println("Name with ID:" + id + " is " + name + ", and messegeID is " + msgId + ", and return is " + result);

  Prosedur tersimpan getName yang digunakan dalam kode di atas adalah sebagai berikut:

  CREATE OR REPLACE FUNCTION getName(
      id        In      Integer,
      name      Out     Varchar2,
      result    Out     Integer
    ) Return Integer
  Is
    ret     Int;
  Begin
    ret := 0;
    name := 'Test';
    result := 1;
    Return(ret);
  End;

  Catatan

  Jika prosedur tersimpan menggunakan kursor, tipe kursor bergantung pada versi Java:

  • Untuk Java 8 dan versi yang lebih baru, gunakan tipe Types.REF_CURSOR.

  • Untuk versi sebelum Java 8, gunakan tipe Types.REF.

• Set FetchSize

  Secara default, driver mengambil semua data dari database sekaligus. Untuk kueri yang melibatkan data dalam jumlah besar, hal ini dapat mengonsumsi banyak memori klien bahkan menyebabkan error kehabisan memori (OOM). Untuk mencegah masalah ini, JDBC menyediakan ResultSet berbasis kursor untuk mengambil set data secara batch. Untuk menggunakan fitur ini:

  • Atur FetchSize. Secara default, FetchSize bernilai 0, yang menunjukkan bahwa driver mengambil semua data.

  • Atur parameter autoCommit dari koneksi ke false.

  // pastikan autocommit dimatikan
  conn.setAutoCommit(false);
  Statement st = conn.createStatement();
  
  // Set fetchSize untuk menggunakan kursor
  st.setFetchSize(50);
  ResultSet rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("sebuah baris dikembalikan.");
  }
  rs.close();
  
  // Reset fetchSize untuk mematikan kursor
  st.setFetchSize(0);
  rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("banyak baris dikembalikan.");
  }
  rs.close();
  
  // Tutup pernyataan.
  st.close();

Proyek Maven

Jika proyek Java Anda dibangun menggunakan Maven, jalankan perintah berikut untuk menginstal paket driver JDBC PolarDB ke repositori lokal Anda:

 mvn install:install-file -DgroupId=com.aliyun -DartifactId=<jar_package_name> -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/<jar_package_name.jar>

Contoh:

 mvn install:install-file -DgroupId=com.aliyun -DartifactId=polardb-jdbc18 -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/polardb-jdbc18.jar

Tambahkan dependensi berikut ke file pom.xml proyek Maven Anda.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId><jar_package_name></artifactId>
    <version>1.1.2</version>
</dependency>

Contoh:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>polardb-jdbc18</artifactId>
    <version>1.1.2</version>
</dependency>

Hibernate

Jika proyek Anda menggunakan Hibernate untuk menghubungkan ke database, konfigurasikan kelas driver dan dialek untuk database PolarDB dalam file konfigurasi hibernate.cfg.xml Anda.

<property name="connection.driver_class">com.aliyun.polardb.Driver</property>
<property name="connection.url">jdbc:polardb://pc-***.o.polardb.rds.aliyuncs.com:1521/polardb_test</property>
<property name="dialect">org.hibernate.dialect.PostgresPlusDialect</property>

Kolam koneksi Druid

• Karena Druid 1.1.24 dan versi yang lebih baru secara native mendukung driver PolarDB, Anda tidak perlu mengatur parameter driver name atau dbtype.

• Untuk versi Druid sebelum 1.1.24, Anda harus secara eksplisit mengatur parameter driver name dan dbtype, seperti berikut:

  dataSource.setDriverClassName("com.aliyun.polardb.Driver");
  dataSource.setDbType("postgresql");

  Catatan

  Versi Druid sebelum 1.1.24 tidak mendukung PolarDB secara native. Oleh karena itu, Anda harus mengatur db-type ke postgresql.

Untuk mengenkripsi password database dalam kolam koneksi Druid, lihat Enkripsi password database.

Adaptasi ke Activiti

Jika aplikasi Anda menggunakan framework manajemen proses bisnis (BPM) Activiti, pesan error berikut mungkin muncul saat Anda menginisialisasi sumber data PolarDB.

couldn't deduct database type from database product name 'POLARDB Database Compatible with Oracle'

Error ini terjadi karena Activiti memiliki pemetaan bawaan antara versi database dan tipe database, yang mencegahnya memetakan informasi versi PolarDB dengan benar. Untuk mengatasi masalah ini, buat kelas turunan SpringProcessEngineConfiguration dan muat ulang metode buildProcessEngine dalam kelas turunan tersebut. Dalam solusi ini, Anda harus secara eksplisit menentukan tipe database, seperti yang ditunjukkan pada contoh berikut.

package com.aliyun.polardb;

import org.activiti.engine.ProcessEngine;
import org.activiti.spring.SpringProcessEngineConfiguration;

public class PolarDBSpringProcessEngineConfiguration extends SpringProcessEngineConfiguration {

    public PolarDBSpringProcessEngineConfiguration() {
        super();
    }

    @Override
    public ProcessEngine buildProcessEngine() {
        setDatabaseType(DATABASE_TYPE_POSTGRES);
        return super.buildProcessEngine();
    }
}

Tempatkan kelas turunan SpringProcessEngineConfiguration dalam proyek Anda. Dalam file konfigurasi, tentukan bahwa kelas ini digunakan untuk memuat konfigurasi dan menginisialisasi engine, seperti yang ditunjukkan pada contoh berikut.

<bean id="processEngineConfiguration" class="com.aliyun.polardb.PolarDBSpringProcessEngineConfiguration">
      <property name="dataSource" ref="dataSource"/>
      <property name="transactionManager" ref="transactionManager"/>
      <property name="databaseSchemaUpdate" value="true"/>
      <!-- Konfigurasi lainnya dihilangkan di sini. -->
</bean>

Adaptasi ke Quartz

org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.PostgreSQLDelegate

Adaptasi ke WebSphere

Adaptasi ke MyBatis

Saat Anda menggunakan MyBatis, Anda mungkin perlu mengonfigurasi databaseIdProvider. Konfigurasi default-nya adalah sebagai berikut:

<databaseIdProvider type="DB_VENDOR">
  <property name="SQL Server" value="sqlserver"/>
  <property name="DB2" value="db2"/>
  <property name="Oracle" value="oracle" />
</databaseIdProvider>

Tujuan databaseIdProvider adalah memetakan database product name ke nama tertentu (databaseId). Hal ini memastikan bahwa meskipun nama produk database berubah setelah pembaruan versi, nama tersebut tetap dipetakan ke nama yang sama.

Dalam file pemetaan XML MyBatis, Anda dapat menentukan atribut databaseId untuk pernyataan SQL. Hal ini memastikan bahwa pernyataan SQL hanya dieksekusi pada database yang sesuai dengan databaseId tersebut. Saat MyBatis memuat file pemetaan XML, hanya pernyataan SQL yang databaseId-nya cocok dengan database saat ini yang dimuat. Pernyataan SQL yang tidak memiliki atribut databaseId selalu dimuat.

  <property name="POLARDB" value="polardb" />

FAQ

• T: Bagaimana cara memilih driver JDBC? Apakah saya bisa menggunakan driver dari komunitas open source?

  J: PolarDB for PostgreSQL (Compatible with Oracle) didasarkan pada PostgreSQL open source dan mencakup banyak fitur untuk kompatibilitas. Beberapa fitur ini memerlukan dukungan tingkat driver. Oleh karena itu, kami menyarankan Anda menggunakan driver JDBC resmi PolarDB, yang dapat Anda unduh dari situs web resmi.

• T: Apakah driver JDBC PolarDB tersedia di repositori Maven publik?

  Satu-satunya metode yang didukung adalah mengunduh paket driver JDBC dari situs web resmi. Untuk proyek Maven, Anda harus menginstal paket ini secara manual ke repositori lokal Anda.

• T: Bagaimana cara melihat nomor versi?

  J: Jalankan perintah java -jar driver_name untuk melihat nomor versi.

• T: Apakah saya bisa mengonfigurasi beberapa alamat IP dan port dalam URL?

  J: Ya, driver JDBC untuk PolarDB for PostgreSQL (Compatible with Oracle) mendukung beberapa alamat IP dan port dalam URL. Berikut adalah contohnya:

  jdbc:poalardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres

  Catatan

  Setelah Anda mengonfigurasi beberapa alamat IP, driver akan mencoba membuat koneksi menggunakan alamat IP tersebut secara berurutan. Jika koneksi tidak dapat dibuat dengan salah satu alamat IP, upaya koneksi akan gagal. Periode timeout default untuk setiap upaya koneksi adalah 10 detik. Nilai ini dikontrol oleh parameter connectTimeout. Untuk mengubah periode timeout, tambahkan parameter ini ke string koneksi.

• T: Bagaimana cara memilih tipe kursor?

  J: Jika Anda menggunakan versi JDK sebelum Java 1.8, gunakan Types.REF. Jika Anda menggunakan Java 1.8 atau versi yang lebih baru, Anda dapat menggunakan Types.REF_CURSOR.

• T: Apakah nama kolom dapat dikembalikan dalam huruf kapital secara default?

  J: Ya, Anda bisa. Tambahkan parameter oracleCase=true ke string koneksi JDBC. Parameter ini mengonversi nama kolom yang dikembalikan ke huruf kapital secara default. Berikut adalah contohnya:

  jdbc:poalardb://1.2.XX.XX:5432,2.3.XX.XX:5432/postgres?oracleCase=true