Hologres：JDBC

Catatan penggunaan

• Untuk menulis data ke Hologres menggunakan JDBC, gunakan PostgreSQL JDBC Driver versi 42.3.2 atau lebih baru.

• Jika Anda menggunakan JDBC untuk menghubungkan ke Hologres dan ingin menguji kinerja penulisan data, disarankan untuk menggunakan virtual private cloud (VPC). Internet tidak cocok untuk pengujian kinerja penulisan data.

• Hologres tidak mendukung penulisan data ganda dalam satu transaksi. Oleh karena itu, atur parameter autoCommit menjadi true untuk mengaktifkan mode auto-commit, alih-alih melakukan commit eksplisit dalam kode. Jika menggunakan PostgreSQL JDBC Driver, mode auto-commit diaktifkan secara default. Jika muncul pesan kesalahan ERROR:INSERT in transaction is not supported now, pastikan untuk mengatur autoCommit menjadi true. Contoh kode:

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

Gunakan JDBC untuk menghubungkan ke Hologres

Untuk menggunakan JDBC dalam menghubungkan ke Hologres, ikuti langkah-langkah berikut:

1. Unduh dan konfigurasikan PostgreSQL JDBC Driver.

   Jika alat klien yang digunakan sudah mengintegrasikan PostgreSQL JDBC Driver secara default, Anda dapat memanfaatkan driver bawaan tersebut. Namun, jika alat klien tidak menyertakan driver ini, unduh dan instal PostgreSQL JDBC Driver.

   Untuk mengunduh PostgreSQL JDBC Driver, kunjungi situs web Maven repository. Pastikan untuk mengunduh versi 42.3.2 atau lebih baru. Kami merekomendasikan penggunaan versi terbaru. Setelah itu, tambahkan driver sebagai dependensi ke Maven repository Anda. Contoh kode:

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

2. Hubungkan ke instance Hologres.

   • Gunakan URL JDBC berikut untuk menghubungkan ke instance Hologres:

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

   • Tabel berikut menjelaskan parameter dalam URL JDBC.

     Parameter	Deskripsi
     ENDPOINT	Titik akhir dan nomor port dari instance Hologres. Masuk ke konsol Hologres. Di panel navigasi sisi kiri, klik Instances. Pada halaman Instances, klik ID instance. Pada halaman Instance Details, lihat titik akhir dan nomor port di bagian Network Information. Penting Pilih titik akhir dan nomor port yang benar berdasarkan lingkungan jaringan tempat kode berjalan. Jika tidak, koneksi tidak akan berfungsi dengan baik.
     PORT
     DBNAME	Nama database Hologres.
     ACCESS_ID	ID AccessKey yang digunakan untuk masuk ke instance Hologres. Kami merekomendasikan agar Anda mengonfigurasi variabel lingkungan dan memperoleh ID AccessKey dan Rahasia AccessKey dari variabel lingkungan. Ini membantu mengurangi risiko kebocoran. Untuk informasi lebih lanjut, lihat contoh-contoh berikut.
     ACCESS_KEY	Rahasia AccecssKey yang digunakan untuk masuk ke instance Hologres. Kami merekomendasikan agar Anda mengonfigurasi variabel lingkungan dan memperoleh ID AccessKey dan Rahasia AccessKey dari variabel lingkungan. Ini membantu mengurangi risiko kebocoran. Untuk informasi lebih lanjut, lihat contoh-contoh berikut.

   • Perhatikan rekomendasi berikut saat menghubungkan ke instance Hologres:

     • Disarankan untuk mengonfigurasi parameter opsional ApplicationName dalam URL JDBC. Dengan mengonfigurasi parameter ApplicationName, Anda dapat mengidentifikasi aplikasi yang mengirim permintaan pada halaman Historical Slow Query. Format URL JDBC:

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

     • Tambahkan reWriteBatchedInserts=true ke URL JDBC untuk memungkinkan beberapa entri data ditulis sekaligus, sehingga meningkatkan kinerja penulisan data. Format URL JDBC:

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

     • Untuk meningkatkan throughput, disarankan membaca dan menulis data dengan mengeksekusi pernyataan yang disiapkan.

     • Setelah fitur pembuatan tabel asing otomatis untuk MaxCompute diaktifkan di Hologres, proyek MaxCompute dipetakan secara otomatis ke skema Hologres dengan nama yang sama. Untuk menanyakan data menggunakan tabel asing dalam skema, konfigurasikan parameter currentSchema dalam URL JDBC. Parameter ini membantu mengidentifikasi proyek MaxCompute yang dipetakan ke skema. Contoh URL JDBC lengkap:

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

     • Untuk mengurangi risiko kebocoran, disarankan mengonfigurasi variabel lingkungan dan memperoleh ID AccessKey serta Rahasia AccessKey dari variabel tersebut. Pada sistem operasi Linux (OS), tambahkan pernyataan berikut ke file bash_profile untuk mengonfigurasi variabel lingkungan:

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

   • Contoh kode berikut menunjukkan cara menghubungkan ke Hologres:

     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()) {
                             // Tanyakan nilai kolom pertama dalam 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());
                     }
                 }
             }
         }
      }

Gunakan JDBC untuk mengembangkan data

Setelah terhubung ke Hologres menggunakan JDBC, Anda dapat menggunakan pernyataan SQL standar untuk mengembangkan data di Hologres, seperti menulis atau membaca data.

• Menulis Data

  Anda dapat menulis data ke Hologres menggunakan pernyataan JDBC atau pernyataan yang disiapkan. Secara umum, disarankan menggunakan pernyataan yang disiapkan dan mengatur jumlah entri data yang akan ditulis sekaligus menjadi 256 atau kelipatan 256. Hal ini mengurangi latensi penulisan data dan meningkatkan throughput karena klien menyimpan hasil kompilasi SQL ketika pernyataan yang disiapkan dieksekusi.

  Dalam contoh ini, data ditulis dengan mengeksekusi pernyataan yang disiapkan.

  • Eksekusi pernyataan berikut untuk menulis data dalam batch:

    /* Tulis data dalam batch dengan mengeksekusi pernyataan yang disiapkan. */
    /* Dalam contoh ini, parameter batchSize diatur ke 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();
        }
    }

  • Anda juga dapat menambahkan pernyataan INSERT ON CONFLICT ke pernyataan yang disiapkan untuk menulis dan memperbarui data. Contoh pernyataan:

    Catatan

    Jika Anda menambahkan pernyataan INSERT ON CONFLICT, pastikan kunci utama telah didefinisikan untuk tabel tujuan.

    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 menanyakan data yang telah ditulis. Anda juga dapat menanyakan data dalam tabel yang ada sesuai kebutuhan bisnis Anda.

Gunakan kumpulan koneksi Druid

• Catatan Penggunaan

  • Disarankan mengonfigurasi keepAlive=true untuk menggunakan kembali koneksi dan mencegah koneksi singkat.

  • Druid versi 1.1.12 atau lebih baru diperlukan untuk menghubungkan ke Hologres.

  • Untuk versi Druid dari 1.2.12 hingga 1.2.21, jika parameter connectTimeout dan socketTimeout tidak dikonfigurasi, nilai default mereka yaitu 10 detik akan digunakan. Untuk menyelesaikan masalah ini, tingkatkan versi Druid.

• Konfigurasikan Kumpulan Koneksi Druid

  Catatan

  Konfigurasikan parameter initialSize, minIdle, dan maxActive berdasarkan ukuran instance Hologres Anda dan kebutuhan bisnis Anda.

  <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource" init-method="init" destroy-method="close">
    <!-- jdbc_url: titik akhir dari instance Hologres yang ingin Anda hubungkan. Anda dapat memperoleh titik akhir pada halaman Instance Details di konsol Hologres. -->
    <property name="url" value="${jdbc_url}" />
    <!-- jdbc_user: ID AccessKey yang digunakan untuk menghubungkan ke instance Hologres.  -->
    <property name="username" value="${jdbc_user}" />
    <!-- jdbc_password: Rahasia AccessKey yang digunakan untuk menghubungkan ke instance Hologres.  -->
    <property name="password" value="${jdbc_password}" />
    <!-- Tentukan ukuran awal kumpulan koneksi, serta jumlah minimum dan maksimum koneksi.  -->
    <property name="initialSize" value="5" />
    <property name="minIdle" value="10" />
    <property name="maxActive" value="20" />
    <!-- Tentukan periode timeout untuk memperoleh koneksi dari kumpulan koneksi.  -->
    <property name="maxWait" value="60000" />
    <!-- Tentukan interval di mana sistem mendeteksi koneksi idle untuk ditutup. Unit: milidetik.  -->
    <property name="timeBetweenEvictionRunsMillis" value="2000" />
    <!-- Tentukan periode validitas minimum koneksi dalam kumpulan koneksi. Unit: milidetik.  -->
    <property name="minEvictableIdleTimeMillis" value="600000" />
    <property name="maxEvictableIdleTimeMillis" value="900000" />
    <property name="validationQuery" value="select 1" />
    <property name="testWhileIdle" value="true" />
    <!-- Tentukan apakah akan memeriksa validitas koneksi setiap kali Anda memperoleh koneksi dari kumpulan koneksi. Nilai true menentukan bahwa sistem memeriksa validitas koneksi, dan nilai false menentukan bahwa sistem tidak memeriksa validitas koneksi.  -->
    <property name="testOnBorrow" value="false" />
    <!-- Tentukan apakah akan memeriksa validitas koneksi setiap kali Anda mengembalikan koneksi ke kumpulan koneksi. Nilai true menentukan bahwa sistem memeriksa validitas koneksi, dan nilai false menentukan bahwa sistem tidak memeriksa validitas koneksi.  -->
    <property name="testOnReturn" value="false" />
    <property name="keepAlive" value="true" />
    <property name="phyMaxUseCount" value="100000" />
    <!-- Konfigurasikan filter yang digunakan untuk pemantauan statistik.  -->
    <property name="filters" value="stat" />
  </bean>

Praktik terbaik untuk optimasi kinerja

Konfigurasikan parameter GUC untuk 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) {
        // Tentukan titik akhir dari instance Hologres.
        String hostname = "hgpostcn-cn-xxxx-cn-hangzhou.hologres.aliyuncs.com";
        // Tentukan nomor port dari instance Hologres.
        String port = "80";
        // Tentukan nama database yang ingin Anda hubungkan.
        String dbname = "demo";
        String jdbcUrl = "jdbc:postgresql://" + hostname + ":" + port + "/" + dbname;
        Properties properties = new Properties();
        //Tentukan akun yang digunakan untuk menghubungkan ke database tertentu.
        properties.setProperty("user", "xxxxx");
        // Tentukan kata sandi akun yang digunakan untuk menghubungkan ke database tertentu.
        properties.setProperty("password", "xxxx");
        // Konfigurasikan 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

Pada Hologres versi 1.3 dan lebih baru, Anda dapat menggunakan JDBC untuk mengonfigurasi beberapa instance sekunder hanya-baca guna mengimplementasikan load balancing sederhana. Untuk informasi lebih lanjut, lihat load balancing berbasis JDBC.