Hologres：JDBC

Perhatian

• Gunakan PostgreSQL JDBC Driver versi 42.3.2 atau yang lebih baru untuk menulis data ke Hologres melalui koneksi JDBC.

• Untuk pengujian performa penulisan data, gunakan jaringan VPC. Jaringan publik tidak memadai untuk tujuan pengujian performa.

• Hologres tidak mendukung penulisan ganda dalam satu transaksi. Oleh karena itu, atur autoCommit ke true. Nilai default autoCommit untuk JDBC adalah true. Jangan panggil operasi commit secara eksplisit dalam kode Anda. Jika muncul error ERROR: INSERT in transaction is not supported now, atur autoCommit ke true, seperti pada contoh berikut.

  Connection conn = DriverManager.getConnection(url, user, password); 
  conn.setAutoCommit(true);

Hubungkan ke Hologres menggunakan JDBC

Ikuti langkah-langkah berikut untuk terhubung ke Hologres menggunakan JDBC.

1. Unduh konfigurasi.

   Kebanyakan alat klien sudah menyertakan driver PostgreSQL bawaan. Gunakan driver bawaan tersebut jika tersedia. Jika tidak, unduh dan instal driver tersebut.

   Untuk menggunakan driver PostgreSQL, kunjungi situs resmi untuk mengunduh PostgreSQL JDBC Driver. Gunakan versi 42.3.2 atau yang lebih baru. Disarankan untuk menggunakan versi terbaru driver JDBC. Setelah diunduh, tambahkan dependensi berikut ke Repositori Maven Anda.

   <dependencies>
           <dependency>
               <groupId>org.postgresql</groupId>
               <artifactId>postgresql</artifactId>
               <version>42.3.2</version>                            
           </dependency>
   </dependencies>

2. Hubungkan ke Hologres.

   • Gunakan string koneksi berikut untuk terhubung ke Hologres.

     jdbc:postgresql://{ENDPOINT}:{PORT}/{DBNAME}?user={ACCESS_ID}&password={ACCESS_KEY}

   • Tabel berikut menjelaskan parameter-parameter tersebut.

     Parameter	Deskripsi
     ENDPOINT	Titik akhir jaringan dan Port instans Hologres. Buka Konsol Hologres. Di panel navigasi sebelah kiri, klik Instances. Klik instans yang dituju. Pada halaman Instance Details, temukan titik akhir dan port di bagian Network Information. Penting Pilih titik akhir dan port yang sesuai dengan lingkungan jaringan tempat kode Anda berjalan. Jika tidak, koneksi akan gagal.
     PORT
     DBNAME	Nama database yang dibuat di Hologres.
     ACCESS_ID	Username untuk akun saat ini. Kami menyarankan Anda menggunakan Variabel lingkungan untuk menentukan kredensial guna mengurangi risiko kebocoran. Untuk informasi selengkapnya, lihat contoh di bagian akhir topik ini.
     ACCESS_KEY	Kata sandi logon untuk akun saat ini. Kami menyarankan Anda menggunakan Variabel lingkungan untuk menentukan kredensial guna mengurangi risiko kebocoran. Untuk informasi selengkapnya, lihat contoh di bagian akhir topik ini.

   • Perhatikan rekomendasi berikut saat menghubungkan ke Hologres.

     • Tambahkan parameter ApplicationName ke URL JDBC. Parameter ini bersifat opsional dan membantu Anda mengidentifikasi aplikasi yang mengirim permintaan berdasarkan ApplicationName dalam daftar periksa kueri lambat. Kode berikut menunjukkan contoh string koneksi.

       jdbc:postgresql://{ENDPOINT}:{PORT}/{DBNAME}?user={ACCESS_ID}&password={ACCESS_KEY}&ApplicationName={APPLICATION_NAME}

     • Tambahkan konfigurasi reWriteBatchedInserts=true ke URL JDBC untuk mengaktifkan pengiriman pekerjaan secara batch guna meningkatkan performa. Kode berikut menunjukkan contoh string koneksi.

       jdbc:postgresql://{ENDPOINT}:{PORT}/{DBNAME}?ApplicationName={APPLICATION_NAME}&reWriteBatchedInserts=true

     • Gunakan Prepared Statement untuk membaca dan menulis data guna mencapai throughput yang lebih tinggi.

     • Setelah Anda mengaktifkan pemuatan otomatis tabel eksternal di Hologres, nama Proyek MaxCompute akan dipetakan secara otomatis ke skema dengan nama yang sama di Hologres. Jika ingin langsung melakukan kueri pada tabel eksternal di skema tersebut, tambahkan parameter currentSchema ke URL JDBC untuk memetakan ke Proyek MaxCompute yang sesuai. Kode berikut menunjukkan contoh string koneksi.

       jdbc:postgresql://{ENDPOINT}:{PORT}/{DBNAME}?currentSchema={SCHEMA_NAME}&user={ACCESS_ID}&password={ACCESS_KEY}&ApplicationName={APPLICATION_NAME}

     • Gunakan Variabel lingkungan untuk menentukan username dan password guna mengurangi risiko kebocoran kredensial. Misalnya, pada sistem Linux, tambahkan perintah berikut ke file bash_profile untuk mengonfigurasi Variabel lingkungan.

       export ALIBABA_CLOUD_USER=<ACCESS_ID>
       export ALIBABA_CLOUD_PASSWORD=<ACCESS_KEY>

   • Kode berikut memberikan contoh koneksi.

     public class HologresTest {
     
         private void jdbcExample() throws SQLException {
             String user= System.getenv("ALIBABA_CLOUD_USER");
             String password = System.getenv("ALIBABA_CLOUD_PASSWORD");
             String url = String.format("jdbc:postgresql://{ENDPOINT}:{PORT}/{DBNAME}?currentSchema={SCHEMA_NAME}&user=%s&password=%s", user, password);
             try (Connection conn = DriverManager.getConnection(url)) {
                 try (Statement st = conn.createStatement()) {
                     String sql = "SELECT * FROM table where xxx limit 100";
                     try (ResultSet rs = st.executeQuery(sql)) {
                         while (rs.next()) {
                             // Dapatkan nilai dari kolom pertama tabel data.
                             String c1 = rs.getString(1);
                         }
                     }
                 }
             }
         }
     
         private void jdbcPreparedStmtExample() throws SQLException {
             String user= System.getenv("ALIBABA_CLOUD_USER");
             String password = System.getenv("ALIBABA_CLOUD_PASSWORD");
             String url = String.format("jdbc:postgresql://{ENDPOINT}:{PORT}/{DBNAME}?currentSchema={SCHEMA_NAME}&user=%s&password=%s", user, password);
             try (Connection conn = DriverManager.getConnection(url)) {
                 String sql = "insert into test values" +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?), " +
                         "(?, ?)";
                 try (PreparedStatement st = conn.prepareStatement(sql)) {
                     for (int i = 0; i < 10; ++i) {
                         for (int j = 0; j < 2 * 10; ++j) {
                             st.setString(j + 1, UUID.randomUUID().toString());
                         }
                         System.out.println("affected row => " + st.executeUpdate());
                     }
                 }
             }
         }
      }

Kembangkan menggunakan JDBC

Setelah terhubung ke Hologres menggunakan JDBC, Anda dapat menggunakan pernyataan standar untuk mengembangkan di Hologres, termasuk menulis dan membaca data.

• Menulis Data

  Anda dapat menulis data menggunakan mode Statement atau Prepared Statement di JDBC. Disarankan menggunakan Prepared Statement dengan ukuran batch kelipatan 256. Ukuran batch minimum yang disarankan adalah 256. Dalam mode Prepared Statement, cache hasil kompilasi SQL disimpan di sisi server, sehingga mengurangi latensi penulisan dan meningkatkan throughput.

  Contoh berikut menunjukkan cara menulis data dalam mode Prepared Statement.

  • Gunakan Prepared Statement untuk menulis data secara batch. Kode berikut merupakan contohnya.

    /*Tulis data secara batch dalam mode Prepared Statement.*/
    /*Dalam contoh ini, ukuran batch adalah 256.*/
    private static void WriteBatchWithPreparedStatement(Connection conn) throws Exception {
        try (PreparedStatement stmt = conn.prepareStatement("insert into test_tb values (?,?,?,?)")) {
            int batchSize = 256;
            for (int i = 0; i < batchSize; ++i) {
                stmt.setInt( 1, 1000 + i);
                stmt.setString( 2, "1");
                SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
                Date parsedDate = dateFormat.parse("1990-11-11 00:00:00");
                stmt.setTimestamp( 3, new java.sql.Timestamp(parsedDate.getTime()));
                stmt.setDouble( 4 , 0.1 );
                stmt.addBatch();
            }
            stmt.executeBatch();
        }
    }

  • Saat menulis data dalam mode Prepared Statement, Anda juga dapat menggunakan fitur PostgreSQL INSERT ON CONFLICT untuk memperbarui atau menimpa data yang sudah ada. Kode berikut merupakan contohnya.

    Catatan

    Tabel tujuan harus memiliki primary key saat menggunakan pernyataan INSERT ON CONFLICT.

    private static void InsertOverwrite(Connection conn) throws Exception {
        try (PreparedStatement stmt = conn.prepareStatement("insert into test_tb values (?,?,?,?), (?,?,?,?), (?,?,?,?), (?,?,?,?), (?,?,?,?), (?,?,?,?) on conflict(pk) do update set f1 = excluded.f1, f2 = excluded.f2, f3 = excluded.f3")) {
            int batchSize = 6;
            for (int i = 0; i < batchSize; ++i) {
                stmt.setInt(i * 4 + 1, i);
                stmt.setString(i * 4 + 2, "1");
                SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
                Date parsedDate = dateFormat.parse("1990-11-11 00:00:00");
                stmt.setTimestamp(i * 4 + 3, new java.sql.Timestamp(parsedDate.getTime()));
                stmt.setDouble(i * 4 + 4, 0.1);
            }
            int affected_rows = stmt.executeUpdate();
            System.out.println("affected rows => " + affected_rows);
        }
    }

• Menanyakan Data

  Setelah data ditulis, Anda dapat melakukan kueri terhadapnya. Anda juga dapat melakukan kueri terhadap tabel yang sudah ada sesuai kebutuhan.

Konfigurasi connection pool Druid

• Perhatian

  • Atur keepAlive=true untuk menggunakan kembali koneksi dan menghindari koneksi singkat.

  • Gunakan Druid versi 1.1.12 atau yang lebih baru untuk terhubung ke Hologres.

  • Versi Druid 1.2.12 hingga 1.2.21 memiliki masalah di mana parameter connectTimeout dan socketTimeout secara default bernilai 10 detik jika tidak ditentukan. Jika mengalami masalah serupa, lakukan upgrade versi Druid Anda.

• Konfigurasikan connection pool Druid

  Catatan

  Atur initialSize, minIdle, dan maxActive berdasarkan ukuran instans dan kebutuhan bisnis Anda.

  <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource" init-method="init" destroy-method="close">
    <!-- jdbc_url adalah URL titik akhir instans Hologres. Anda dapat memperoleh URL tersebut dari halaman konfigurasi instans di konsol. -->
    <property name="url" value="${jdbc_url}" />
    <!-- jdbc_user adalah ID AccessKey akun pengguna di instans Hologres. -->
    <property name="username" value="${jdbc_user}" />
    <!-- jdbc_password adalah Rahasia AccessKey yang sesuai dengan akun pengguna di instans Hologres. -->
    <property name="password" value="${jdbc_password}" />
    <!-- Konfigurasikan ukuran awal, jumlah minimum koneksi, dan jumlah maksimum koneksi untuk connection pool. -->
    <property name="initialSize" value="5" />
    <property name="minIdle" value="10" />
    <property name="maxActive" value="20" />
    <!-- Konfigurasikan periode timeout untuk menunggu koneksi. -->
    <property name="maxWait" value="60000" />
    <!-- Konfigurasikan interval untuk mendeteksi dan menutup koneksi idle. Satuan: milidetik. -->
    <property name="timeBetweenEvictionRunsMillis" value="2000" />
    <!-- Konfigurasikan waktu hidup minimum untuk koneksi dalam pool. Satuan: milidetik. -->
    <property name="minEvictableIdleTimeMillis" value="600000" />
    <property name="maxEvictableIdleTimeMillis" value="900000" />
    <property name="validationQuery" value="select 1" />
    <property name="testWhileIdle" value="true" />
    <!-- Konfigurasikan apakah akan memeriksa validitas koneksi saat diambil dari pool. true: periksa setiap kali. false: jangan periksa. -->
    <property name="testOnBorrow" value="false" />
    <!-- Konfigurasikan apakah akan memeriksa validitas koneksi saat dikembalikan ke pool. true: periksa setiap kali. false: jangan periksa. -->
    <property name="testOnReturn" value="false" />
    <property name="keepAlive" value="true" />
    <property name="phyMaxUseCount" value="100000" />
    <!-- Konfigurasikan filter untuk pemantauan dan intersepsi statistik. -->
    <property name="filters" value="stat" />
  </bean>

Praktik terbaik tuning performa

Konfigurasi parameter GUC menggunakan JDBC

import org.postgresql.PGProperty;
import java.sql.*;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;

public class gucdemo {
    public static void main(String[] args) {
        // Atur endpoint instans Hologres.
        String hostname = "hgpostcn-cn-xxxx-cn-hangzhou.hologres.aliyuncs.com";
        // Atur port instans Hologres.
        String port = "80";
        // Atur nama database yang akan dihubungkan.
        String dbname = "demo";
        String jdbcUrl = "jdbc:postgresql://" + hostname + ":" + port + "/" + dbname;
        Properties properties = new Properties();
        // Atur username untuk koneksi database.
        properties.setProperty("user", "xxxxx");
        //Atur password untuk koneksi database.
        properties.setProperty("password", "xxxx");
        // Atur parameter GUC.
        PGProperty.OPTIONS.set(properties,"--statement_timeout=12345 --idle_in_transaction_session_timeout=12345");
        try {
            Class.forName("org.postgresql.Driver");
            Connection connection = DriverManager.getConnection(jdbcUrl, properties);
            PreparedStatement preparedStatement = connection.prepareStatement("show statement_timeout" );
            ResultSet resultSet = preparedStatement.executeQuery();
            while (resultSet.next()) {
                ResultSetMetaData rsmd = resultSet.getMetaData();
                int columnCount = rsmd.getColumnCount();
                Map map = new HashMap();
                for (int i = 0; i < columnCount; i++) {
                    map.put(rsmd.getColumnName(i + 1).toLowerCase(), resultSet.getObject(i + 1));
                }
                System.out.println(map);
            }
        } catch (Exception exception) {
            exception.printStackTrace();
        }
    }
}

Load balancing berbasis JDBC

Mulai dari V1.3, Hologres memungkinkan Anda mengonfigurasi beberapa instans secondary read-only dalam JDBC untuk mendukung load balancing sederhana. Untuk informasi selengkapnya, lihat Load balancing berbasis JDBC.