Menghubungkan Aplikasi Java ke AlloyDB untuk PostgreSQL dengan Autentikasi IAM

1. Sebelum memulai

AlloyDB untuk PostgreSQL adalah layanan database Google Cloud yang kompatibel dengan PostgreSQL dan terkelola sepenuhnya untuk workload perusahaan yang berat. Menghubungkan aplikasi Java ke AlloyDB dengan aman dan efisien dilakukan melalui AlloyDB Java Connector (alloydb-jdbc-connector), library klien yang lebih dari sekadar driver JDBC standar.

Keajaiban Konektor Java AlloyDB

alloydb-jdbc-connector berfungsi sebagai SocketFactory cerdas untuk driver JDBC PostgreSQL standar (org.postgresql:postgresql). Driver ini mengabstraksi pembuatan koneksi database yang aman sehingga Anda dapat berfokus pada logika aplikasi, bukan keamanan jaringan atau rotasi kredensial:

• Enkripsi mTLS 1.3: Otomatis membuat koneksi TLS 1.3 yang saling diautentikasi antara JVM dan instance AlloyDB tanpa mengharuskan Anda mengelola sertifikat klien SSL/TLS secara manual.
• Otorisasi Berbasis IAM: Alih-alih mengandalkan sandi database statis, konektor memanfaatkan Google Cloud IAM dan Kredensial Default Aplikasi (ADC) untuk mendapatkan token akses OAuth2 berumur pendek secara otomatis.
• Dynamic IP Resolution: Mengkueri AlloyDB Admin API untuk me-resolve alamat IP saat ini (PRIVATE, PUBLIC, atau Private Service Connect PSC) dari instance database Anda secara dinamis. Anda tidak perlu melakukan hard code pada nama host atau alamat IP, sehingga failover dan pemeliharaan menjadi transparan.

Catatan Arsitektur — Konektor AlloyDB Java vs. Proxy Auth AlloyDB: Untuk aplikasi JVM, Konektor AlloyDB Java berjalan dalam proses sebagai SocketFactory JDBC, sehingga menghilangkan overhead operasional dalam men-deploy dan mengelola container sidecar terpisah. Cadangkan biner Proxy Auth AlloyDB mandiri untuk alat non-JVM, aplikasi lama yang tidak dapat Anda ubah classpath JDBC-nya, atau lingkungan yang mewajibkan proxy eksternal.

Prasyarat

• Pemahaman tentang Java, Maven, dan konsep dasar SQL/JDBC.
• Pemahaman dasar tentang Google Cloud CLI (gcloud) dan peran IAM.

Yang akan Anda lakukan

• Mengonfigurasi instance AlloyDB dan Akun Layanan untuk Autentikasi Database IAM tanpa sandi.
• Memberikan izin skema dan tabel PostgreSQL dengan hak istimewa terendah kepada akun utama IAM.
• Konfigurasikan DataSource berkelas produksi dengan Plain JDBC dan HikariCP menggunakan SocketFactory AlloyDB.
• Mengintegrasikan Konektor Java AlloyDB di aplikasi Spring Boot, Quarkus, dan Micronaut.
• Daftarkan SocketFactory AlloyDB untuk kompilasi GraalVM Native Image dan pecahkan masalah umum terkait autentikasi IAM.

Yang Anda butuhkan

• Project Google Cloud dengan penagihan yang diaktifkan serta Cluster dan Instance Utama AlloyDB yang aktif (lihat panduan pembuatan cluster AlloyDB atau jalankan cluster AlloyDB Express dalam waktu kurang dari dua detik).
• Peran IAM roles/alloydb.admin dan roles/resourcemanager.projectIamAdmin di project Anda.
• Java 17 atau yang lebih tinggi (direkomendasikan Java 17 atau 21 LTS) dan Apache Maven telah diinstal.
• gcloud CLI dan klien psql telah diinstal (atau akses ke Google Cloud Shell).

2. Menyiapkan Autentikasi Database IAM di AlloyDB

Sebelum menulis kode Java, Anda perlu mengonfigurasi instance AlloyDB untuk menerima token IAM dan membuat identitas IAM yang akan digunakan aplikasi Anda di tiga lapisan: Google Cloud IAM, Bidang Kontrol AlloyDB, dan Mesin PostgreSQL.

Menetapkan Variabel Lingkungan

Di terminal Anda, ekspor variabel yang sesuai dengan project Google Cloud dan instance AlloyDB Anda (ganti placeholder dengan nilai Anda):

export PROJECT_ID="<PROJECT_ID>"
export REGION="europe-west1"
export CLUSTER_ID="<CLUSTER_ID>"
export INSTANCE_ID="<INSTANCE_ID>"
export DB_NAME="dvdrental"

Mengaktifkan API yang Diperlukan

Aktifkan AlloyDB, Compute Engine, Cloud Resource Manager, IAM, dan Service Usage API di project Anda:

gcloud services enable \
    alloydb.googleapis.com \
    compute.googleapis.com \
    cloudresourcemanager.googleapis.com \
    iam.googleapis.com \
    serviceusage.googleapis.com \
    --project="${PROJECT_ID}"

Membuat Akun Layanan dan Memberikan Peran IAM

Buat Akun Layanan khusus yang akan berfungsi sebagai identitas aplikasi Java Anda:

gcloud iam service-accounts create java-alloydb-connector \
    --project="${PROJECT_ID}" \
    --display-name="Java Application DB Connector"

Berikan dua peran IAM yang diperlukan oleh Konektor Java AlloyDB ke Akun Layanan:

1. roles/alloydb.client: Diperlukan untuk mengambil metadata instance dan meminta sertifikat mTLS sementara dari AlloyDB Admin API.
2. roles/serviceusage.serviceUsageConsumer: Diperlukan untuk autentikasi database IAM.

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/alloydb.client"

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/serviceusage.serviceUsageConsumer"

Mengaktifkan Autentikasi IAM di Instance AlloyDB

Perbarui flag instance AlloyDB Anda untuk menetapkan alloydb.iam_authentication=on. Flag ini bersifat dinamis dan langsung berlaku tanpa memulai ulang instance:

gcloud alloydb instances update "${INSTANCE_ID}" \
    --cluster="${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --database-flags=alloydb.iam_authentication=on

Mendaftarkan Pengguna Database IAM

Daftarkan Akun Layanan sebagai pengguna database IAM_BASED di cluster AlloyDB Anda menggunakan gcloud:

gcloud alloydb users create "java-alloydb-connector@${PROJECT_ID}.iam" \
    --cluster="${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --type=IAM_BASED

Aturan Penamaan & Bidang Kontrol yang Penting:

1. Hapus .gserviceaccount.com: Untuk Akun Layanan, nama pengguna AlloyDB tidak boleh menyertakan akhiran .gserviceaccount.com (java-alloydb-connector@.iam).
2. Gunakan gcloud, Terraform, atau Konsol Cloud: Jangan mencoba membuat pengguna IAM melalui CREATE USER ...; GRANT alloydbiamuser TO ...; SQL mentah. AlloyDB membatasi pemberian peran alloydbiamuser internal ke bidang kontrol (ERROR: grant or revoke of role "alloydbiamuser" is not allowed).

Memberikan Izin Skema dan Tabel PostgreSQL

Pengguna database IAM yang baru dibuat tidak memiliki hak istimewa tabel secara default. Hubungkan ke instance AlloyDB Anda sebagai pengguna admin postgres (melalui psql atau AlloyDB Studio di Konsol Cloud) dan berikan akses ke database dan tabel target Anda (seperti database contoh DVD Rental):

-- Connect to your target database first
\c dvdrental

-- (Optional) Create a sample film table if your database is empty
CREATE TABLE IF NOT EXISTS public.film (
    film_id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    release_year INTEGER DEFAULT 2006,
    rating VARCHAR(10) DEFAULT 'PG',
    rental_rate NUMERIC(4,2) DEFAULT 2.99
);

INSERT INTO public.film (film_id, title, release_year, rating, rental_rate) VALUES
    (1, 'Academy Dinosaur', 2006, 'PG', 0.99),
    (2, 'Ace Goldfinger', 2006, 'G', 4.99),
    (3, 'Adaptation Holes', 2006, 'NC-17', 2.99),
    (4, 'Affair Prejudice', 2006, 'G', 2.99),
    (5, 'African Egg', 2006, 'G', 2.99)
ON CONFLICT (film_id) DO NOTHING;

-- Grant permissions to the IAM user (double quotes are required because of '@' and '.')
GRANT CONNECT ON DATABASE "dvdrental" TO "java-alloydb-connector@<PROJECT_ID>.iam";
GRANT USAGE ON SCHEMA public TO "java-alloydb-connector@<PROJECT_ID>.iam";
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "java-alloydb-connector@<PROJECT_ID>.iam";

Saat menjalankan pernyataan ini di AlloyDB Studio (atau psql), Anda dapat memeriksa skema public.film dan memverifikasi baris contoh:

Mengonfigurasi Kredensial Default Aplikasi (ADC) Lokal

Saat berjalan di Cloud Run, Google Kubernetes Engine (GKE), atau Compute Engine, lampirkan Akun Layanan java-alloydb-connector langsung ke workload. Saat berjalan secara lokal di workstation Anda, tiru Akun Layanan agar ADC membuat token untuk identitas tersebut:

gcloud auth application-default login \
    --impersonate-service-account="java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com"

Pintasan Pengembangan Lokal: Sebagai alternatif, Anda dapat mendaftarkan email pengguna Google Cloud Anda sendiri sebagai pengguna IAM (gcloud alloydb users create --cluster=${CLUSTER_ID} --region=${REGION} --type=IAM_BASED), memberinya izin tabel SQL yang sama, dan menjalankan gcloud auth application-default login tanpa peniruan akun layanan.

3. Menghubungkan dengan JDBC Biasa dan HikariCP

Untuk aplikasi Java tingkat produksi, connection pool sangat penting, dan HikariCP adalah standar industri. Pada langkah ini, Anda akan membangun aplikasi JDBC + HikariCP biasa yang mendelegasikan pembuatan soket ke com.google.cloud.alloydb.SocketFactory.

Membuat Project Maven (pom.xml)

Buat direktori baru jdbc-app dengan file pom.xml yang berisi driver JDBC PostgreSQL (42.7.14), Konektor Java AlloyDB (1.4.0), dan HikariCP (7.1.0):

mkdir -p jdbc-app/src/main/java
cd jdbc-app

Buat pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example.alloydb</groupId>
    <artifactId>alloydb-jdbc-sample</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <exec.mainClass>AlloyDBConnectivity</exec.mainClass>
    </properties>

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

        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>alloydb-jdbc-connector</artifactId>
            <version>1.4.0</version>
        </dependency>

        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>7.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.16</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <cleanupDaemonThreads>false</cleanupDaemonThreads>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Catatan Koordinat Maven: Pastikan untuk menggunakan com.google.cloud untuk alloydb-jdbc-connector di pom.xml Anda. Meskipun class Java SocketFactory berada dalam paket com.google.cloud.alloydb, artefak Maven dipublikasikan di bawah groupId com.google.cloud.

Tips — Selalu Perbarui Versi Dependensi: Versi baru alloydb-jdbc-connector, driver JDBC PostgreSQL (org.postgresql:postgresql), HikariCP, dan BOM framework (Spring Boot, Quarkus, Micronaut) dirilis secara berkala dengan peningkatan keamanan dan performa. Pertimbangkan untuk memeriksa Maven Central atau menjalankan mvn versions:display-dependency-updates untuk mengupdate dependensi pom.xml Anda ke rilis terbaru.

Buat AlloyDBConnectivity.java

Buat src/main/java/AlloyDBConnectivity.java (lihat di GitHub Gist):

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

public class AlloyDBConnectivity {
    // Retrieve configuration from environment variables
    private static final String ALLOYDB_INSTANCE_URI = System.getenv("ALLOYDB_INSTANCE_NAME"); // e.g., projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>
    private static final String ALLOYDB_DB_NAME = System.getenv("ALLOYDB_DB"); // e.g., "dvdrental"
    private static final String ALLOYDB_USER = System.getenv("ALLOYDB_USER"); // e.g., "java-alloydb-connector@<PROJECT_ID>.iam"
    private static final String ALLOYDB_PASS = System.getenv("ALLOYDB_PASS"); // Database password if not using IAM auth

    public static HikariDataSource createDataSource() {
        HikariConfig config = new HikariConfig();

        // The JDBC URL does not need a host or port. The SocketFactory will resolve the IP address.
        config.setJdbcUrl(String.format("jdbc:postgresql:///%s", ALLOYDB_DB_NAME));
        config.setUsername(ALLOYDB_USER);

        // Only set the password if you are NOT using IAM authentication.
        if (System.getenv("ALLOYDB_ENABLE_IAM_AUTH") == null || !System.getenv("ALLOYDB_ENABLE_IAM_AUTH").equalsIgnoreCase("true")) {
            config.setPassword(ALLOYDB_PASS);
        }

        // 1. Set the SocketFactory to the AlloyDB Connector's implementation.
        config.addDataSourceProperty("socketFactory", "com.google.cloud.alloydb.SocketFactory");

        // 2. Tell the connector which AlloyDB instance to connect to.
        config.addDataSourceProperty("alloydbInstanceName", ALLOYDB_INSTANCE_URI);

        // 3. (Recommended) Enable IAM database authentication.
        if (System.getenv("ALLOYDB_ENABLE_IAM_AUTH") != null && System.getenv("ALLOYDB_ENABLE_IAM_AUTH").equalsIgnoreCase("true")) {
            config.addDataSourceProperty("alloydbEnableIAMAuth", "true");
        }

        // 4. (Optional) Specify IP type (e.g., "PRIVATE", "PUBLIC", "PSC"). Defaults to PRIVATE.
        String ipType = System.getenv("ALLOYDB_IP_TYPE");
        if (ipType != null) {
            config.addDataSourceProperty("alloydbIpType", ipType);
        }

        // Baseline HikariCP settings
        config.setMaximumPoolSize(10);
        config.setMinimumIdle(2);
        config.setConnectionTimeout(30000); // 30 seconds
        config.setIdleTimeout(600000);      // 10 minutes
        config.setMaxLifetime(1800000);     // 30 minutes

        return new HikariDataSource(config);
    }

    public static void main(String[] args) {
        String sql = "SELECT title, release_year FROM public.film ORDER BY film_id LIMIT 5";

        try (HikariDataSource pool = createDataSource();
             Connection conn = pool.getConnection();
             PreparedStatement stmt = conn.prepareStatement(sql);
             ResultSet rs = stmt.executeQuery()) {
            System.out.println("Successfully connected to AlloyDB via IAM! Sample films:");
            while (rs.next()) {
                System.out.printf(" - %s (%d)%n", rs.getString("title"), rs.getInt("release_year"));
            }
        } catch (SQLException e) {
            System.err.println("Database connection failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Konsep Utama — Alasan URL JDBC Tidak Memiliki Host atau Port: Perhatikan bahwa jdbc:postgresql:///%s berisi tiga garis miring dan tidak memiliki nama host atau port. Saat socketFactory=com.google.cloud.alloydb.SocketFactory ditetapkan, driver PostgreSQL mendelegasikan pembuatan soket ke Konektor AlloyDB, yang mencari URI alloydbInstanceName melalui AlloyDB Admin API dan terhubung langsung ke IP yang di-resolve melalui mTLS 1.3.

Menjalankan Aplikasi JDBC Biasa

Ekspor variabel lingkungan untuk instance AlloyDB Anda (tetapkan ALLOYDB_IP_TYPE="PUBLIC" jika terhubung dari luar VPC melalui IP Publik, atau "PRIVATE" / "PSC" saat berada di dalam VPC) dan jalankan aplikasi:

export ALLOYDB_INSTANCE_NAME="projects/${PROJECT_ID}/locations/${REGION}/clusters/${CLUSTER_ID}/instances/${INSTANCE_ID}"
export ALLOYDB_DB="${DB_NAME}"
export ALLOYDB_USER="java-alloydb-connector@${PROJECT_ID}.iam"
export ALLOYDB_ENABLE_IAM_AUTH="true"
export ALLOYDB_IP_TYPE="PRIVATE" # Set to PUBLIC if connecting over Public IP from a local laptop

mvn compile exec:java

Anda akan melihat output yang mirip dengan:

[AlloyDBConnectivity.main()] INFO com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
[AlloyDBConnectivity.main()] INFO com.zaxxer.hikari.pool.HikariPool - HikariPool-1 - Added connection org.postgresql.jdbc.PgConnection@1998bf07
[AlloyDBConnectivity.main()] INFO com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
Successfully connected to AlloyDB via IAM! Sample films:
 - Academy Dinosaur (2006)
 - Ace Goldfinger (2006)
 - Adaptation Holes (2006)
 - Affair Prejudice (2006)
 - African Egg (2006)

4. Terhubung dengan Spring Boot

Spring Boot menyederhanakan konektivitas database dengan mengonfigurasi kumpulan koneksi HikariCP secara otomatis dari properti aplikasi Anda. Mengintegrasikan Konektor AlloyDB Java tidak memerlukan kode bean DataSource kustom.

Membuat Project Spring Boot (pom.xml)

Buat direktori baru spring-boot-app:

cd ..
mkdir -p spring-boot-app/src/main/java/com/example/alloydb
mkdir -p spring-boot-app/src/main/resources
cd spring-boot-app

Buat pom.xml dengan spring-boot-starter-jdbc (yang mencakup HikariCP), org.postgresql:postgresql, dan com.google.cloud:alloydb-jdbc-connector:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.0.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example.alloydb</groupId>
    <artifactId>alloydb-spring-boot-sample</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.7.14</version>
        </dependency>

        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>alloydb-jdbc-connector</artifactId>
            <version>1.4.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Mengonfigurasi application.properties atau Variabel Lingkungan

Anda dapat mengonfigurasi URL koneksi di src/main/resources/application.properties:

# No host or port is needed; the SocketFactory handles it.
spring.datasource.url=jdbc:postgresql:///dvdrental?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>&alloydbEnableIAMAuth=true
spring.datasource.username=java-alloydb-connector@<PROJECT_ID>.iam
# No password required when alloydbEnableIAMAuth is true

Agar file sumber Anda sepenuhnya bebas dari project ID atau nama instance, Anda dapat mengosongkan application.properties dan menyediakan variabel lingkungan Spring Boot standar ini saat runtime:

Variabel Lingkungan	Nilai
SPRING_DATASOURCE_URL	jdbc:postgresql:///dvdrental?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects//locations//clusters//instances/&alloydbEnableIAMAuth=true
SPRING_DATASOURCE_USERNAME	java-alloydb-connector@.iam

Tips Spring Cloud GCP & Secret Manager:

• Jika Anda lebih memilih properti terstruktur daripada URL JDBC yang panjang, Anda dapat menggunakan com.google.cloud:spring-cloud-gcp-starter-alloydb dan menetapkan spring.cloud.gcp.alloydb.database-name, spring.cloud.gcp.alloydb.instance-connection-uri, dan spring.cloud.gcp.alloydb.iam-auth-enabled=true.
• Jika organisasi Anda masih memerlukan sandi database statis, bukan autentikasi IAM, jangan pernah melakukan hard code pada sandi tersebut. Memasukkannya secara dinamis dari Google Cloud Secret Manager menggunakan spring.config.import=sm:// dan spring.datasource.password=${sm://alloydb-password}.

Buat AlloyDbTestApplication.java

Buat src/main/java/com/example/alloydb/AlloyDbTestApplication.java (lihat di GitHub Gist):

package com.example.alloydb;

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.jdbc.core.JdbcTemplate;

@SpringBootApplication
public class AlloyDbTestApplication {

    public static void main(String[] args) {
        System.exit(SpringApplication.exit(SpringApplication.run(AlloyDbTestApplication.class, args)));
    }

    @Bean
    CommandLineRunner testConnection(JdbcTemplate jdbcTemplate) {
        return args -> {
            String result = jdbcTemplate.queryForObject("SELECT 'Connection Successful!'", String.class);
            System.out.println(">>> ALLOYDB STATUS: " + result);
        };
    }
}

Menjalankan Aplikasi Spring Boot

Ekspor variabel lingkungan dan jalankan aplikasi dengan mvn spring-boot:run:

export SPRING_DATASOURCE_URL="jdbc:postgresql:///${DB_NAME}?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects/${PROJECT_ID}/locations/${REGION}/clusters/${CLUSTER_ID}/instances/${INSTANCE_ID}&alloydbEnableIAMAuth=true"
export SPRING_DATASOURCE_USERNAME="java-alloydb-connector@${PROJECT_ID}.iam"

mvn spring-boot:run

Anda akan melihat:

>>> ALLOYDB STATUS: Connection Successful!

5. Terhubung dengan Quarkus, Micronaut, dan GraalVM Native Image

Karena Konektor Java AlloyDB beroperasi di level driver JDBC, beralih antara framework Java berbasis cloud tidak akan mengubah cara Anda mengamankan traffic database atau mengelola identitas. Quarkus dan Micronaut menggabungkan driver JDBC yang mendasarinya dan mendelegasikan enkripsi mTLS, resolusi IP dinamis, dan autentikasi IAM ke konektor melalui ADC.

Konfigurasi Quarkus (application.properties dengan Agroal)

Dalam aplikasi Quarkus (quarkus-agroal dan quarkus-jdbc-postgresql), tambahkan com.google.cloud:alloydb-jdbc-connector:1.4.0 ke dependensi Anda dan teruskan parameter konektor melalui quarkus.datasource.jdbc.additional-jdbc-properties di src/main/resources/application.properties:

quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=java-alloydb-connector@<PROJECT_ID>.iam
quarkus.datasource.jdbc.url=jdbc:postgresql:///dvdrental
quarkus.datasource.jdbc.additional-jdbc-properties.socketFactory=com.google.cloud.alloydb.SocketFactory
quarkus.datasource.jdbc.additional-jdbc-properties.alloydbInstanceName=projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>
quarkus.datasource.jdbc.additional-jdbc-properties.alloydbEnableIAMAuth=true

Tips Preseden BOM untuk Quarkus & Micronaut: Saat menggunakan com.google.cloud:alloydb-jdbc-connector:1.4.0 dalam project dengan quarkus-bom atau micronaut-parent, impor com.google.cloud:libraries-bom terlebih dahulu di bagian . Hal ini memastikan bahwa versi protobuf-java (4.x) dan gRPC yang lebih baru yang diperlukan oleh klien AlloyDB Admin lebih diprioritaskan daripada versi lama yang dikelola oleh BOM framework.

Konfigurasi Micronaut (application.yml dengan HikariCP)

Dalam aplikasi Micronaut (micronaut-jdbc-hikari), tambahkan com.google.cloud:alloydb-jdbc-connector:1.4.0 dan konfigurasikan src/main/resources/application.yml:

datasources:
  default:
    url: jdbc:postgresql:///dvdrental?socketFactory=com.google.cloud.alloydb.SocketFactory&alloydbInstanceName=projects/<PROJECT_ID>/locations/<REGION>/clusters/<CLUSTER_ID>/instances/<INSTANCE_ID>&alloydbEnableIAMAuth=true
    username: java-alloydb-connector@<PROJECT_ID>.iam
    driver-class-name: org.postgresql.Driver

Mendaftarkan Connector untuk Image Native GraalVM

Saat mengompilasi aplikasi Anda ke dalam Image Native GraalVM (dengan Spring Boot 3+, Quarkus, atau Micronaut), ada satu detail penting: Refleksi.

Driver JDBC PostgreSQL membuat instance com.google.cloud.alloydb.SocketFactory secara dinamis berdasarkan nama class menggunakan refleksi. Untuk mencegah analisis statis GraalVM menghapus class selama kompilasi native, daftarkan class secara eksplisit:

• Spring Boot 3+: Tambahkan @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class) ke aplikasi utama atau class @Configuration Anda:

  @SpringBootApplication
  @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class)
  public class AlloyDbTestApplication { ... }
  

• Quarkus: Tambahkan @RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class) ke class utama atau bean CDI:

  @QuarkusMain
  @RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class)
  public class QuarkusAlloyDbApp implements QuarkusApplication { ... }
  

6. Memecahkan Masalah IAM dan Konektivitas Umum

Jika Anda mengalami error FATAL: password authentication failed for user atau AlloyDB IAM authentication failed, verifikasi empat area berikut:

1. Menghapus .gserviceaccount.com dari Nama Pengguna Database Akun Layanan

Penyebab paling sering dari kegagalan autentikasi IAM adalah meneruskan alamat email Akun Layanan lengkap sebagai nama pengguna database. AlloyDB memformat nama pengguna database IAM secara berbeda, bergantung pada jenis akun utama:

• Untuk Akun Layanan IAM (hapus .gserviceaccount.com): Jika email Akun Layanan Google Cloud Anda adalah java-alloydb-connector@.iam.gserviceaccount.com, Anda harus menghapus akhiran .gserviceaccount.com dan menetapkan nama pengguna database JDBC/AlloyDB Anda ke java-alloydb-connector@.iam.
• Untuk Akun Pengguna atau Grup IAM (pertahankan email lengkap): Jika Anda melakukan autentikasi sebagai pengguna Google Workspace atau Cloud Identity, gunakan alamat email lengkap Anda tanpa diubah (misalnya, ).

2. Memverifikasi Cara Pengguna Database Dibuat

Apakah Anda mendaftarkan pengguna melalui gcloud alloydb users create --type=IAM_BASED (atau Konsol/Terraform)? Membuat pengguna dengan SQL mentah CREATE USER tidak akan berfungsi untuk autentikasi IAM karena AlloyDB membatasi GRANT alloydbiamuser ke bidang kontrol.

3. Memverifikasi Identitas ADC Aktif Anda

Pastikan lingkungan tempat proses Java berjalan benar-benar diautentikasi sebagai akun utama IAM target:

• Workstation Lokal (terhubung sebagai Akun Layanan): Jalankan gcloud auth application-default login --impersonate-service-account=java-alloydb-connector@.iam.gserviceaccount.com agar ADC membuat token untuk Akun Layanan, bukan email pribadi Anda.
• Cloud Run/GKE: Pastikan Akun Layanan dilampirkan ke workload dan memiliki roles/alloydb.client dan roles/serviceusage.serviceUsageConsumer.

4. Memperhitungkan Propagasi IAM & Pemilihan Rute Jaringan

• Penundaan Penerapan IAM: Binding kebijakan IAM dapat memerlukan waktu 60–120 detik untuk diterapkan. Jika Anda baru saja membuat Akun Layanan atau binding peran, tunggu sebentar dan coba lagi.
• Akses Jaringan VPC: Secara default, Konektor AlloyDB Java terhubung ke IP PRIVATE instance. Jika aplikasi Anda berjalan di Cloud Run, konfigurasikan Egress VPC Langsung (direkomendasikan untuk latensi dan biaya yang lebih rendah dibandingkan Konektor Akses VPC Serverless lama) atau hubungkan melalui Private Service Connect (PSC). Jika terhubung dari mesin lokal di luar VPC, aktifkan IP Publik pada instance dan teruskan alloydbIpType=PUBLIC.

7. Pembersihan

Agar tidak menimbulkan biaya yang tidak perlu pada akun Google Cloud Anda dan untuk menghapus identitas IAM yang dibuat selama codelab ini, bersihkan resource di bawah.

1. Menghapus Akun Layanan dan Pengguna Database IAM AlloyDB

Hapus pengguna database IAM dari cluster AlloyDB Anda dan hapus Akun Layanan:

# Delete the IAM database user from AlloyDB
gcloud alloydb users delete "java-alloydb-connector@${PROJECT_ID}.iam" \
    --cluster="${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --quiet

# Remove IAM policy bindings
gcloud projects remove-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/alloydb.client"

gcloud projects remove-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/serviceusage.serviceUsageConsumer"

# Delete the Service Account
gcloud iam service-accounts delete \
    "java-alloydb-connector@${PROJECT_ID}.iam.gserviceaccount.com" \
    --project="${PROJECT_ID}" \
    --quiet

2. Mereset Kredensial Default Aplikasi Lokal

Jika Anda mengonfigurasi peniruan identitas ADC lokal, reset kredensial lokal Anda kembali ke identitas pengguna default:

gcloud auth application-default login

3. (Opsional) Menghapus Cluster AlloyDB

Perhatian: Menghapus cluster AlloyDB akan menghancurkan semua instance dan database di dalamnya secara permanen. Hanya jalankan perintah di bawah jika Anda membuat cluster pengujian khusus untuk codelab ini.

gcloud alloydb clusters delete "${CLUSTER_ID}" \
    --region="${REGION}" \
    --project="${PROJECT_ID}" \
    --force \
    --quiet

8. Selamat

Anda telah menyelesaikan codelab dan membuat konektivitas yang aman dan tanpa sandi dari Java ke AlloyDB untuk PostgreSQL.

Yang telah Anda capai

1. Mengonfigurasi Autentikasi Database IAM: Membuat Akun Layanan dengan hak istimewa terendah, mengaktifkan alloydb.iam_authentication=on, mendaftarkan pengguna IAM di cluster AlloyDB, dan memberikan hak istimewa tabel PostgreSQL.
2. Terhubung dengan Plain JDBC & HikariCP: Mengonfigurasi HikariConfig dengan com.google.cloud.alloydb.SocketFactory untuk enkripsi mTLS 1.3 otomatis, pembaruan token IAM, dan resolusi IP dinamis.
3. Framework Berbasis Cloud Terintegrasi: Mengonfigurasi Spring Boot, Quarkus (Agroal), dan Micronaut (HikariCP) dengan boilerplate connection pool kustom tanpa kode, plus petunjuk refleksi untuk GraalVM Native Image.
4. Menguasai Pemecahan Masalah IAM: Mempelajari cara mendiagnosis masalah pemformatan nama pengguna, peniruan identitas ADC, dan perutean VPC.

Pelajari Lebih Lanjut

• Dokumentasi AlloyDB untuk PostgreSQL
• Repositori GitHub Konektor Java AlloyDB
• Ringkasan Koneksi AlloyDB
• Ringkasan AlloyDB Express
• Dokumentasi AlloyDB Omni