PolarDB：JDBC

Unduh paket driver JDBC

Unduh driver JDBC (42.2.9.1.6)

Alibaba Cloud menyediakan tiga versi driver JDBC. Pilih versi berdasarkan versi Java Development Kit (JDK) yang digunakan oleh aplikasi Anda. Untuk Java 6, unduh file JAR polardb-jdbc16.jar. Untuk Java 7, unduh file JAR polardb-jdbc17.jar. Untuk Java 8, unduh file JAR polardb-jdbc18.jar.

Konfigurasi driver JDBC

Sebelum menggunakan driver JDBC dalam aplikasi Java Anda, tambahkan jalur driver JDBC ke CLASSPATH. Sebagai contoh, jika jalur driver JDBC adalah /usr/local/polardb/share/java/, jalankan perintah berikut untuk menambahkan jalur driver JDBC ke CLASSPATH:

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

Contoh:

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

Jalankan perintah berikut untuk melihat versi JDBC saat ini:

#java -jar <Nama file JAR.jar>

Contoh:

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

Hubungkan ke PolarDB

• Examples

  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 IP host tempat demo ini dijalankan ada 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, jalankan perintah berikut untuk memuat driver JDBC:

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

• Connect to a database

  Dalam kebanyakan kasus, database direpresentasikan oleh URL dalam JDBC. Contoh:

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

  Parameter	Contoh	Deskripsi
  Prefiks URL	jdbc:polardb://	Prefiks URL. Semua prefiks URL kluster PolarDB adalah jdbc:polardb://.
  Titik akhir	pc-***.o.polardb.rds.aliyuncs.com	Titik akhir kluster PolarDB. Untuk informasi tentang cara melihat titik akhir, lihat Lihat atau ajukan permohonan untuk titik akhir.
  Nomor port	1521	Port kluster PolarDB. Nilai default: 1521.
  Database	polardb_test	Nama database yang ingin Anda hubungkan.
  Nama pengguna	test	Nama pengguna yang digunakan untuk menghubungkan ke kluster PolarDB.
  Kata sandi	Pw123456	Kata sandi nama pengguna yang digunakan untuk menghubungkan ke kluster PolarDB.

• Run a query and process the query result

  Sebelum menjalankan kueri pada database, Anda harus membuat objek Statement, PreparedStatment, atau CallableStatement.

  Dalam contoh sebelumnya, sebuah objek Statement dibuat. Dalam kode sampel berikut, sebuah objek PreparedStatment dibuat:

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

  Kode berikut memberikan contoh tentang cara menggunakan CallableStatement untuk memproses prosedur tersimpan:

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

  Untuk membuat prosedur tersimpan getName yang digunakan dalam contoh sebelumnya, jalankan perintah 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 Anda ingin menggunakan kursor dalam prosedur tersimpan, Anda harus memilih jenis kursor berdasarkan versi Java Anda.

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

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

• Configure FetchSize

  Secara default, driver mengambil semua data yang diperlukan dari database sekaligus. Jika volume data yang ingin Anda kueri besar, sejumlah besar memori akan dikonsumsi. Akibatnya, kesalahan out-of-memory (OOM) dapat terjadi. Untuk mencegah kesalahan OOM, driver JDBC menyediakan objek ResultSet berbasis kursor untuk membantu Anda mengambil beberapa dataset sekaligus. Untuk menggunakan ResultSet, konfigurasikan parameter berikut:

  • FetchSize: Nilai defaultnya adalah 0. Jika Anda mengatur ResultSet ke 0, semua data diambil.

  • autoCommit: Atur nilainya 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();

Siapkan proyek Java menggunakan Maven

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

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

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId><Nama file JAR></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 terhubung ke database, konfigurasikan kelas driver dan dialek database PolarDB dalam file konfigurasi Hibernate bernama hibernate.cfg.xml.

<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

• Secara default, Druid 1.1.24 dan versi lebih baru mendukung driver JDBC PolarDB. Anda tidak perlu mengonfigurasi parameter driver name dan dbtype.

• Untuk versi Druid sebelum 1.1.24, konfigurasikan parameter driver name dan dbtype secara eksplisit, seperti yang ditunjukkan dalam contoh berikut:

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

  Catatan

  Versi Druid sebelum 1.1.24 tidak disesuaikan dengan PolarDB. Oleh karena itu, Anda harus mengatur dbtype ke postgresql.

Untuk informasi lebih lanjut tentang cara mengenkripsi kata sandi database dalam kolam koneksi Druid, lihat Enkripsi Kata Sandi Database.

Adaptasi ke Activiti

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

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

Penyebabnya adalah bahwa Activiti menyediakan pemetaan bawaan antara versi database dan jenis database. Versi database tidak dipetakan dengan benar ke PolarDB dalam pemetaan bawaan. Untuk menyelesaikan masalah ini, Anda dapat mengonfigurasi subkelas SpringProcessEngineConfiguration untuk memuat ulang buildProcessEngine ke subkelas. Saat Anda mengonfigurasi subkelas, Anda harus menentukan jenis database secara eksplisit. Contoh:

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

Simpan subkelas SpringProcessEngineConfiguration di proyek Anda dan gunakan subkelas dalam file konfigurasi untuk memuat konfigurasi. Lalu, inisialisasi mesin. Contoh:

<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. -->
</bean>

Adaptasi ke Quartz

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

Adaptasi ke WebSphere

Adaptasi ke MyBatis

Sebelum menggunakan MyBatis untuk terhubung ke PolarDB, Anda mungkin perlu mengonfigurasi file 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 layanan database service ke nama tampilan yang ditentukan oleh properti databaseId. Dengan cara ini, layanan database yang sama dipetakan ke nama tampilan yang sama, bahkan jika nama layanan database bervariasi dengan versi layanan database.

databaseIdProvider adalah file XML. Dalam file ini, Anda dapat menentukan properti databaseId untuk pernyataan SQL. Dengan cara ini, pernyataan SQL hanya dapat dieksekusi di database yang ditentukan oleh properti databaseId. Dalam hal ini, ketika MyBatis memuat file XML, hanya pernyataan SQL yang dipetakan ke database saat ini dan pernyataan SQL yang tidak memiliki databaseId yang dimuat.

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

FAQ

• Bisakah saya menggunakan driver JDBC sumber terbuka, alih-alih driver JDBC dari PolarDB for PostgreSQL (Kompatibel dengan Oracle)?

  PolarDB for PostgreSQL (Kompatibel dengan Oracle) dikembangkan berdasarkan PostgreSQL sumber terbuka dan menyediakan beberapa fitur kompatibilitas. Driver diperlukan untuk mengimplementasikan beberapa fitur ini. Kami merekomendasikan agar Anda menggunakan driver JDBC dari PolarDB for PostgreSQL (Kompatibel dengan Oracle). Driver JDBC dari PolarDB for PostgreSQL (Kompatibel dengan Oracle) dapat diunduh dari situs resmi Alibaba Cloud.

• Bisakah driver JDBC digunakan di repositori Maven publik?

  File JAR driver JDBC hanya dapat diunduh dari situs resmi Alibaba Cloud. Setelah Anda mengunduh file JAR, Anda perlu menginstal file JAR tersebut di repositori lokal Anda untuk proyek-proyek yang dibangun menggunakan Maven.

• Bagaimana cara melihat versi driver JDBC?

  Anda dapat menjalankan perintah java -jar <Nama driver> untuk melihat nomor versi.

• Bisakah saya menentukan beberapa alamat IP dan nomor port dalam URL?

  Ya, Anda dapat menentukan beberapa alamat IP dan nomor port dalam URL saat Anda mengonfigurasi driver JDBC dari PolarDB for PostgreSQL (Kompatibel dengan Oracle). Contoh:

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

  Catatan

  Jika Anda ingin menghubungkan aplikasi Anda ke database setelah mengonfigurasi beberapa alamat IP dalam URL, sistem akan mencoba menghubungkan ke alamat IP tersebut secara berurutan hingga koneksi berhasil dibuat. Jika semua alamat IP tidak dapat dihubungkan, pembuatan koneksi gagal. Waktu tunggu default untuk setiap percobaan koneksi adalah 10 detik. Untuk memodifikasi periode waktu tunggu, Anda dapat menambahkan dan mengonfigurasi parameter connectTimeout dalam URL.

• Bagaimana cara memilih jenis kursor?

  Jika versi Java yang Anda gunakan lebih lama dari 1.8, gunakan Types.REF. Jika tidak, gunakan Types.REF_CURSOR.

• Bagaimana nama kolom yang dikembalikan dapat dikonversi otomatis menjadi huruf besar?

  Tambahkan oracleCase=true ke URL driver JDBC untuk mengubah semua nama kolom yang dikembalikan menjadi huruf besar. Contoh:

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