PolarDB:JDBC

Konfigurasi driver JDBC

Untuk menggunakan driver JDBC dalam aplikasi Java, tambahkan path file JAR-nya ke CLASSPATH Anda. Misalnya, jika file JAR disimpan di direktori /usr/local/polardb/share/java/, jalankan perintah berikut untuk menambahkan path tersebut ke CLASSPATH:

export CLASSPATH=$CLASSPATH:/usr/local/polardb/share/java/<jar-file-name.jar>

Contoh:

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

Untuk memeriksa versi driver JDBC Anda, jalankan perintah berikut:

#java -jar <jar-file-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 ada di daftar putih kluster Anda.
   */
  public class PolarDBJdbcDemo {
    /**
     * Ganti nilai placeholder 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();
    }
  }

• Muat driver JDBC

  Jalankan perintah berikut di aplikasi Anda untuk memuat driver JDBC:

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

• Hubungkan ke database

  Dalam JDBC, URL koneksi merepresentasikan koneksi ke database. Contohnya:

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

  Parameter	Contoh	Deskripsi
  Awalan URL	jdbc:polardb://	Awalan URL untuk menghubungkan ke PolarDB selalu jdbc:polardb://.
  Titik akhir	pc-***.o.polardb.rds.aliyuncs.com	Titik akhir kluster PolarDB. Untuk informasi selengkapnya, lihat View or apply for an endpoint.
  Port	1521	Port kluster PolarDB. Nilai default-nya adalah 1521.
  Database	polardb_test	Nama database yang akan dihubungkan.
  Username	test	Username kluster PolarDB.
  Password	Pw123456	Password untuk username kluster PolarDB.

• Query data and process results

  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));
  }

  CallableStatement digunakan untuk memanggil prosedur tersimpan. Berikut contohnya:

  String sql = "{?=call getName (?, ?, ?)}";
  CallableStatement stmt = conn.prepareCall(sql);
  stmt.registerOutParameter(1, java.sql.Types.INTEGER);
  
  // Bind parameter IN terlebih dahulu, lalu bind parameter OUT
  int id = 100;
  stmt.setInt(2, id); // Ini akan mengatur ID menjadi 102
  stmt.registerOutParameter(3, java.sql.Types.VARCHAR);
  stmt.registerOutParameter(4, java.sql.Types.INTEGER);
  
  // Gunakan metode execute untuk menjalankan prosedur tersimpan.
  stmt.execute();
  
  // Ambil nama dengan metode getXXX
  String name = stmt.getString(3);
  Integer msgId = stmt.getInt(4);
  Integer result = stmt.getInt(1);
  System.out.println("Nama dengan ID:" + id + " adalah " + name + ", dan messageID-nya adalah " + msgId + ", dan return-nya adalah " + result);

  Prosedur tersimpan getName yang digunakan dalam kode di atas didefinisikan 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

  Untuk prosedur tersimpan yang mengembalikan kursor, tipe kursor bergantung pada versi Java:

  • Untuk Java 8 atau yang lebih baru, gunakan Types.REF_CURSOR.

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

• Set the fetch size

  Secara default, driver mengambil semua hasil kueri dari database sekaligus. Untuk set hasil yang besar, hal ini dapat mengonsumsi memori client secara signifikan dan berpotensi menyebabkan error Out of Memory (OOM). Untuk mencegah hal ini, JDBC menyediakan ResultSet berbasis kursor untuk mengambil data secara batch. Untuk menggunakan fitur ini, Anda harus:

  • Mengatur FetchSize. Nilai default FetchSize adalah 0, yang berarti semua data diambil sekaligus.

  • Mengatur properti autoCommit koneksi ke false.

  // pastikan autocommit dimatikan
  conn.setAutoCommit(false);
  Statement st = conn.createStatement();
  
  // Atur fetchSize untuk menggunakan kursor
  st.setFetchSize(50);
  ResultSet rs = st.executeQuery("SELECT * FROM mytable");
  while (rs.next())
  {
      System.out.print("satu baris dikembalikan.");
  }
  rs.close();
  
  // Atur ulang 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 statement.
  st.close();

Integrasi Maven

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

mvn install:install-file -DgroupId=com.aliyun -DartifactId=<jar-file-name> -Dversion=1.1.2 -Dpackaging=jar -Dfile=/usr/local/polardb/share/java/<jar-file-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-file-name></artifactId>
    <version>1.1.2</version>
</dependency>

Contoh:

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

Integrasi Hibernate

Jika proyek Anda menggunakan Hibernate, konfigurasikan kelas driver dan dialek untuk PolarDB di file 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>

Integrasi Druid

• Secara default, Druid 1.1.24 dan versi yang lebih baru mendukung driver PolarDB. Anda tidak perlu mengatur parameter driverClassName dan dbtype.

• Untuk versi sebelum Druid 1.1.24, Anda harus secara eksplisit mengatur parameter driverClassName dan dbtype:

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

  Catatan

  Versi Druid sebelum 1.1.24 tidak memiliki dukungan native untuk PolarDB. Oleh karena itu, Anda harus mengatur parameter dbtype ke postgresql.

Jika Anda perlu mengenkripsi password database di kolam koneksi Druid, lihat Database password encryption.

Integrasi Activiti

Jika aplikasi Anda menggunakan framework Activiti untuk manajemen proses bisnis, error berikut mungkin terjadi saat Anda menginisialisasi sumber data PolarDB.

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

Error ini terjadi karena pemetaan bawaan Activiti dari nama produk database ke tipe database tidak mencakup entri untuk PolarDB. Untuk mengatasinya, buat subclass SpringProcessEngineConfiguration dan override metode buildProcessEngine untuk secara eksplisit menentukan tipe database. Kode berikut menunjukkan contohnya.

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 subclass SpringProcessEngineConfiguration di proyek Anda. Kemudian, di file konfigurasi, atur engine untuk memuat konfigurasi dari kelas ini selama inisialisasi. Kode berikut menunjukkan contohnya.

<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>

Integrasi Quartz

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

Integrasi WebSphere

Integrasi MyBatis

Saat Anda menggunakan MyBatis, Anda mungkin perlu mengonfigurasi databaseIdProvider. Kode berikut menunjukkan konfigurasi default:

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

databaseIdProvider menyediakan pemetaan dari nama produk database ke alias tertentu, yaitu databaseId. Hal ini memastikan bahwa nama produk database dipetakan ke alias yang sama meskipun nama produk berubah di berbagai versi database.

Dalam file pemetaan XML MyBatis, Anda dapat menambahkan atribut databaseId ke pernyataan SQL. Hal ini memastikan pernyataan tersebut hanya dijalankan pada database yang cocok dengan databaseId tersebut. Saat MyBatis memuat file pemetaan, hanya pernyataan dengan databaseId yang cocok dan semua pernyataan tanpa atribut databaseId yang dimuat.

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

FAQ

• Q: Bagaimana cara memilih driver JDBC? Dapatkah saya menggunakan driver komunitas open source?

  A: PolarDB for PostgreSQL (Compatible with Oracle) didasarkan pada PostgreSQL open-source, tetapi beberapa fiturnya memerlukan dukungan tingkat driver. Oleh karena itu, kami menyarankan menggunakan driver JDBC resmi PolarDB, yang dapat Anda unduh dari halaman unduhan driver resmi.

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

  A: Tidak. Driver tersebut tidak tersedia di repositori Maven publik. Anda harus mengunduh file JAR dari situs resmi dan, untuk proyek Maven, menginstalnya secara manual ke repositori lokal Anda.

• Q: Bagaimana cara memeriksa nomor versi driver?

  A: Jalankan perintah java -jar <driver-name> untuk melihat nomor versinya.

• Q: Apakah URL koneksi mendukung beberapa alamat IP dan port?

  A: Ya, driver JDBC PolarDB for PostgreSQL (Compatible with Oracle) memungkinkan Anda menentukan beberapa pasangan host-port di URL koneksi, seperti pada contoh berikut:

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

  Catatan

  Jika Anda mengonfigurasi beberapa alamat IP, driver akan mencoba menghubungkannya secara berurutan. Jika koneksi tidak dapat dibangun dengan salah satu alamat IP tersebut, upaya koneksi gagal. Timeout koneksi default untuk setiap percobaan adalah 10 detik (connectTimeout). Untuk mengubah periode timeout, Anda dapat menambahkan parameter connectTimeout ke string koneksi.

• Q: Bagaimana cara memilih tipe kursor?

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

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

  A: Ya. Tambahkan parameter oracleCase=true ke string koneksi JDBC untuk mengonversi semua nama kolom yang dikembalikan menjadi huruf kapital. Berikut contohnya:

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