आईएएम ऑथेंटिकेशन की मदद से, Java ऐप्लिकेशन को AlloyDB for PostgreSQL से कनेक्ट करना

1. शुरू करने से पहले

AlloyDB for PostgreSQL, Google Cloud की पूरी तरह से मैनेज की जाने वाली डेटाबेस सेवा है. यह PostgreSQL के साथ काम करती है और एंटरप्राइज़ के मुश्किल वर्कलोड को मैनेज करने के लिए डिज़ाइन की गई है. AlloyDB Java Connector (alloydb-jdbc-connector) की मदद से, Java ऐप्लिकेशन को AlloyDB से सुरक्षित और असरदार तरीके से कनेक्ट किया जाता है. यह एक क्लाइंट लाइब्रेरी है, जो स्टैंडर्ड जेडीबीसी ड्राइवर से बेहतर है.

AlloyDB Java Connector का जादू

alloydb-jdbc-connector, स्टैंडर्ड PostgreSQL JDBC ड्राइवर (org.postgresql:postgresql) के लिए स्मार्ट SocketFactory के तौर पर काम करता है. यह सुरक्षित डेटाबेस कनेक्शन बनाने की प्रोसेस को आसान बनाता है, ताकि आप नेटवर्क की सुरक्षा या समय-समय पर पुष्टि से जुड़े क्रेडेंशियल बदलने की प्रक्रिया के बजाय, ऐप्लिकेशन लॉजिक पर ध्यान दे सकें:

• mTLS 1.3 एन्क्रिप्शन: यह आपके जेवीएम और AlloyDB इंस्टेंस के बीच, दोनों तरफ़ से पुष्टि किया गया TLS 1.3 कनेक्शन अपने-आप सेट अप करता है. इसके लिए, आपको एसएसएल/टीएलएस क्लाइंट सर्टिफ़िकेट को मैन्युअल तरीके से मैनेज करने की ज़रूरत नहीं पड़ती.
• आईएएम-आधारित अनुमति: कनेक्टर, स्टैटिक डेटाबेस पासवर्ड पर निर्भर रहने के बजाय, Google Cloud IAM और ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) का इस्तेमाल करता है. इससे कम समय के लिए मान्य OAuth2 ऐक्सेस टोकन अपने-आप मिल जाते हैं.
• डाइनैमिक आईपी रिज़ॉल्यूशन: यह AlloyDB Admin API से क्वेरी करके, आपके डेटाबेस इंस्टेंस के मौजूदा आईपी पते (PRIVATE, PUBLIC या Private Service Connect PSC) को डाइनैमिक तरीके से रिज़ॉल्व करता है. आपको होस्टनेम या आईपी पतों को हार्ड-कोड करने की ज़रूरत नहीं है. इससे फ़ेलओवर और रखरखाव की प्रोसेस पारदर्शी हो जाती है.

आर्किटेक्चर से जुड़ी जानकारी — AlloyDB Java Connector बनाम AlloyDB Auth Proxy: जेवीएम ऐप्लिकेशन के लिए, AlloyDB Java Connector, JDBC SocketFactory के तौर पर इन-प्रोसेस चलता है. इससे, अलग साइडकार कंटेनर को डिप्लॉय और मैनेज करने का ऑपरेशनल ओवरहेड खत्म हो जाता है. स्टैंडअलोन AlloyDB Auth Proxy बाइनरी को नॉन-जेवीएम टूल, लेगसी ऐप्लिकेशन के लिए रिज़र्व करें. इनमें जेडीबीसी क्लासपाथ में बदलाव नहीं किया जा सकता या ऐसे एनवायरमेंट जहां बाहरी प्रॉक्सी ज़रूरी है.

ज़रूरी शर्तें

• Java, Maven, और बुनियादी SQL/JDBC कॉन्सेप्ट की जानकारी.
• Google Cloud सीएलआई (gcloud) और आईएएम की भूमिकाओं के बारे में बुनियादी जानकारी.

आपको क्या करना होगा

• बिना पासवर्ड के IAM डेटाबेस ऑथेंटिकेशन के लिए, AlloyDB इंस्टेंस और सेवा खाता कॉन्फ़िगर करना.
• किसी आईएएम प्रिंसिपल को PostgreSQL स्कीमा और टेबल की कम से कम अनुमतियां दें.
• AlloyDB SocketFactory का इस्तेमाल करके, Plain JDBC और HikariCP के साथ प्रोडक्शन-ग्रेड DataSource को कॉन्फ़िगर करें.
• AlloyDB Java कनेक्टर को Spring Boot, Quarkus, और Micronaut ऐप्लिकेशन में इंटिग्रेट करें.
• GraalVM नेटिव इमेज कंपाइलेशन के लिए, AlloyDB SocketFactory को रजिस्टर करें. साथ ही, आईएएम से पुष्टि करने से जुड़ी सामान्य समस्याओं को हल करें.

आपको किन चीज़ों की ज़रूरत होगी

• बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट और एक चालू AlloyDB क्लस्टर और प्राइमरी इंस्टेंस (AlloyDB क्लस्टर बनाने की गाइड देखें या दो सेकंड से भी कम समय में AlloyDB Express क्लस्टर बनाएं).
• आपके प्रोजेक्ट पर roles/alloydb.admin और roles/resourcemanager.projectIamAdmin आईएएम भूमिकाएं.
• Java 17 या इसके बाद का वर्शन (Java 17 या 21 LTS का सुझाव दिया जाता है) और Apache Maven इंस्टॉल होना चाहिए.
• gcloud सीएलआई और psql क्लाइंट इंस्टॉल किया गया हो या Google Cloud Shell का ऐक्सेस हो.

2. AlloyDB पर आईएएम डेटाबेस ऑथेंटिकेशन सेट अप करना

Java कोड लिखने से पहले, आपको अपने AlloyDB इंस्टेंस को कॉन्फ़िगर करना होगा, ताकि वह आईएएम टोकन स्वीकार कर सके. साथ ही, आपको वह आईएएम आइडेंटिटी बनानी होगी जिसका इस्तेमाल आपका ऐप्लिकेशन तीन लेयर में करेगा: Google Cloud IAM, AlloyDB कंट्रोल प्लेन, और PostgreSQL इंजन.

एनवायरमेंट वैरिएबल सेट करना

अपने टर्मिनल में, Google Cloud प्रोजेक्ट और AlloyDB इंस्टेंस से जुड़े वैरिएबल एक्सपोर्ट करें. इसके लिए, प्लेसहोल्डर को अपनी वैल्यू से बदलें:

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

ज़रूरी एपीआई चालू करना

अपने प्रोजेक्ट में AlloyDB, Compute Engine, Cloud Resource Manager, IAM, और Service Usage API चालू करें:

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

सेवा खाता बनाना और आईएएम की भूमिकाएं देना

एक खास सेवा खाता बनाएं, जो आपके Java ऐप्लिकेशन की पहचान के तौर पर काम करेगा:

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

सेवा खाते को दो आईएएम भूमिकाएं दें, जो AlloyDB Java Connector के लिए ज़रूरी हैं:

1. roles/alloydb.client: AlloyDB Admin API से इंस्टेंस का मेटाडेटा फ़ेच करने और कुछ समय के लिए इस्तेमाल होने वाले एमटीएलएस सर्टिफ़िकेट का अनुरोध करने के लिए ज़रूरी है.
2. roles/serviceusage.serviceUsageConsumer: आईएएम डेटाबेस की पुष्टि करने के लिए ज़रूरी है.

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"

AlloyDB इंस्टेंस पर आईएएम की मदद से पुष्टि करने की सुविधा चालू करना

alloydb.iam_authentication=on सेट करने के लिए, अपने AlloyDB इंस्टेंस के फ़्लैग अपडेट करें. यह एक डाइनैमिक फ़्लैग है और इंस्टेंस को रीस्टार्ट किए बिना तुरंत लागू हो जाता है:

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

IAM डेटाबेस उपयोगकर्ता को रजिस्टर करना

gcloud का इस्तेमाल करके, सेवा खाते को अपने AlloyDB क्लस्टर पर IAM_BASED डेटाबेस उपयोगकर्ता के तौर पर रजिस्टर करें:

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

नाम रखने और कंट्रोल-प्लेन के ज़रूरी नियम:

1. स्ट्रिप .gserviceaccount.com: सेवा खातों के लिए, AlloyDB के उपयोगकर्ता नाम में .gserviceaccount.com सफ़िक्स (java-alloydb-connector@.iam) नहीं होना चाहिए.
2. gcloud, Terraform या Cloud Console का इस्तेमाल करें: रॉ एसक्यूएल CREATE USER ...; GRANT alloydbiamuser TO ...; का इस्तेमाल करके, आईएएम उपयोगकर्ता बनाने की कोशिश न करें. AlloyDB, कंट्रोल प्लेन (ERROR: grant or revoke of role "alloydbiamuser" is not allowed) को इंटरनल alloydbiamuser भूमिका असाइन करने पर पाबंदी लगाता है.

PostgreSQL स्कीमा और टेबल की अनुमतियां देना

नए बनाए गए IAM डेटाबेस उपयोगकर्ताओं के पास, डिफ़ॉल्ट रूप से टेबल के कोई अधिकार नहीं होते. postgres खाते के एडमिन के तौर पर अपने AlloyDB इंस्टेंस से कनेक्ट करें. इसके लिए, psql या Cloud Console में AlloyDB Studio का इस्तेमाल करें. इसके बाद, अपने टारगेट डेटाबेस और टेबल का ऐक्सेस दें. जैसे, डीवीडी रेंटल सैंपल डेटाबेस:

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

AlloyDB Studio (या psql) में इन स्टेटमेंट को चलाते समय, public.film स्कीमा की जांच की जा सकती है. साथ ही, सैंपल पंक्तियों की पुष्टि की जा सकती है:

लोकल ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) कॉन्फ़िगर करना

Cloud Run, Google Kubernetes Engine (GKE) या Compute Engine पर काम करते समय, java-alloydb-connector सेवा खाते को सीधे वर्कलोड से अटैच करें. अपने वर्कस्टेशन पर स्थानीय तौर पर काम करते समय, सेवा खाते का इस्तेमाल करें, ताकि एडीसी उस पहचान के लिए टोकन जनरेट कर सके:

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

लोकल डेवलपमेंट शॉर्टकट: इसके अलावा, आपके पास अपने Google Cloud उपयोगकर्ता ईमेल को IAM उपयोगकर्ता (gcloud alloydb users create --cluster=${CLUSTER_ID} --region=${REGION} --type=IAM_BASED) के तौर पर रजिस्टर करने का विकल्प है. साथ ही, उसे SQL टेबल की वही अनुमतियां दें और सेवा खाते के नाम पर काम किए बिना gcloud auth application-default login चलाएं.

3. Plain JDBC और HikariCP के साथ कनेक्ट करना

किसी भी प्रोडक्शन-ग्रेड Java ऐप्लिकेशन के लिए, कनेक्शन पूल ज़रूरी है. साथ ही, HikariCP इंडस्ट्री स्टैंडर्ड है. इस चरण में, आपको एक सामान्य JDBC + HikariCP ऐप्लिकेशन बनाना होगा, जो सॉकेट बनाने का काम com.google.cloud.alloydb.SocketFactory को सौंपता है.

Maven प्रोजेक्ट (pom.xml) बनाना

jdbc-app नाम की एक नई डायरेक्ट्री बनाएं. इसमें pom.xml फ़ाइल होनी चाहिए, जिसमें PostgreSQL JDBC ड्राइवर (42.7.14), AlloyDB Java Connector (1.4.0), और HikariCP (7.1.0) शामिल हों:

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

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>

Maven कोऑर्डिनेट के बारे में जानकारी: पक्का करें कि आपने pom.xml में alloydb-jdbc-connector के लिए com.google.cloud का इस्तेमाल किया हो. SocketFactory Java क्लास, com.google.cloud.alloydb पैकेज में मौजूद होती है. वहीं, Maven आर्टफ़ैक्ट को com.google.cloud groupId के तहत पब्लिश किया जाता है.

सलाह — डिपेंडेंसी के वर्शन अप-टू-डेट रखें: alloydb-jdbc-connector, PostgreSQL JDBC ड्राइवर (org.postgresql:postgresql), HikariCP, और फ़्रेमवर्क बीओएम (Spring Boot, Quarkus, Micronaut) के नए वर्शन नियमित तौर पर रिलीज़ किए जाते हैं. इनमें सुरक्षा और परफ़ॉर्मेंस से जुड़े सुधार शामिल होते हैं. अपनी pom.xml डिपेंडेंसी को नए वर्शन पर अपडेट करने के लिए, Maven Central देखें या mvn versions:display-dependency-updates चलाएं.

AlloyDBConnectivity.java बनाएं

src/main/java/AlloyDBConnectivity.java बनाएं (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();
        }
    }
}

मुख्य कॉन्सेप्ट — जेडीबीसी यूआरएल में होस्ट या पोर्ट क्यों नहीं होता: ध्यान दें कि jdbc:postgresql:///%s में तीन स्लैश हैं और कोई होस्टनेम या पोर्ट नहीं है. socketFactory=com.google.cloud.alloydb.SocketFactory सेट होने पर, PostgreSQL ड्राइवर सॉकेट बनाने की ज़िम्मेदारी AlloyDB कनेक्टर को सौंपता है. यह कनेक्टर, AlloyDB Admin API के ज़रिए alloydbInstanceName यूआरआई को खोजता है और mTLS 1.3 के ज़रिए रिज़ॉल्व किए गए आईपी से सीधे कनेक्ट करता है.

Plain JDBC ऐप्लिकेशन चलाना

अपने AlloyDB इंस्टेंस के लिए एनवायरमेंट वैरिएबल एक्सपोर्ट करें. अगर वीपीसी के बाहर से सार्वजनिक आईपी पते का इस्तेमाल करके कनेक्ट किया जा रहा है, तो ALLOYDB_IP_TYPE="PUBLIC" सेट करें. इसके अलावा, वीपीसी के अंदर से कनेक्ट करने पर, "PRIVATE" / "PSC" सेट करें. इसके बाद, ऐप्लिकेशन चलाएं:

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

आपको इससे मिलता-जुलता आउटपुट दिखेगा:

[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. Spring Boot से कनेक्ट करना

Spring Boot, आपके ऐप्लिकेशन की प्रॉपर्टी से HikariCP कनेक्शन पूल को अपने-आप कॉन्फ़िगर करके, डेटाबेस कनेक्टिविटी को आसान बनाता है. AlloyDB Java Connector को इंटिग्रेट करने के लिए, कस्टम DataSource बीन कोड की ज़रूरत नहीं होती.

Spring Boot प्रोजेक्ट बनाना (pom.xml)

नई डायरेक्ट्री 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

spring-boot-starter-jdbc (इसमें HikariCP शामिल है), org.postgresql:postgresql, और com.google.cloud:alloydb-jdbc-connector की मदद से 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 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>

application.properties या एनवायरमेंट वैरिएबल कॉन्फ़िगर करना

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

अपनी सोर्स फ़ाइलों को प्रोजेक्ट आईडी या इंस्टेंस के नामों से पूरी तरह से मुक्त रखने के लिए, application.properties को खाली छोड़ा जा सकता है. साथ ही, रनटाइम के दौरान ये स्टैंडर्ड Spring Boot एनवायरमेंट वैरिएबल दिए जा सकते हैं:

एनवायरमेंट वैरिएबल	वैल्यू
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

Spring Cloud GCP और Secret Manager के बारे में सलाह:

• अगर आपको लंबे JDBC यूआरएल के बजाय स्ट्रक्चर्ड प्रॉपर्टी पसंद हैं, तो com.google.cloud:spring-cloud-gcp-starter-alloydb का इस्तेमाल करें. साथ ही, spring.cloud.gcp.alloydb.database-name, spring.cloud.gcp.alloydb.instance-connection-uri, और spring.cloud.gcp.alloydb.iam-auth-enabled=true सेट करें.
• अगर आपके संगठन को अब भी आईएएम ऑथेंटिकेशन के बजाय स्टैटिक डेटाबेस पासवर्ड की ज़रूरत है, तो उन्हें कभी भी हार्ड-कोड न करें. spring.config.import=sm:// और spring.datasource.password=${sm://alloydb-password} का इस्तेमाल करके, Google Cloud Secret Manager से उन्हें डाइनैमिक तौर पर इंजेक्ट करें.

AlloyDbTestApplication.java बनाएं

src/main/java/com/example/alloydb/AlloyDbTestApplication.java बनाएं (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);
        };
    }
}

Spring Boot ऐप्लिकेशन चलाना

एनवायरमेंट वैरिएबल एक्सपोर्ट करें और 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

आपको ये चीज़ें दिखेंगी:

>>> ALLOYDB STATUS: Connection Successful!

5. Quarkus, Micronaut, और GraalVM नेटिव इमेज से कनेक्ट करना

AlloyDB Java Connector, जेडीबीसी ड्राइवर लेवल पर काम करता है. इसलिए, क्लाउड-नेटिव Java फ़्रेमवर्क के बीच स्विच करने से, डेटाबेस ट्रैफ़िक को सुरक्षित रखने या आइडेंटिटी मैनेज करने के तरीके में कोई बदलाव नहीं होता. Quarkus और Micronaut, दोनों ही जेडीबीसी ड्राइवर को रैप करते हैं. साथ ही, एडीसी के ज़रिए कनेक्टर को एमटीएलएस एन्क्रिप्शन, डाइनैमिक आईपी रिज़ॉल्यूशन, और आईएएम से पुष्टि करने की सुविधा देते हैं.

Quarkus कॉन्फ़िगरेशन (Agroal के साथ application.properties)

Quarkus ऐप्लिकेशन (quarkus-agroal और quarkus-jdbc-postgresql) में, अपनी डिपेंडेंसी में com.google.cloud:alloydb-jdbc-connector:1.4.0 जोड़ें. साथ ही, src/main/resources/application.properties में quarkus.datasource.jdbc.additional-jdbc-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

Quarkus और Micronaut के लिए, बीओएम की प्राथमिकता से जुड़ी सलाह: quarkus-bom या micronaut-parent वाले प्रोजेक्ट में com.google.cloud:alloydb-jdbc-connector:1.4.0 का इस्तेमाल करते समय, अपने सेक्शन में com.google.cloud:libraries-bom को सबसे पहले इंपोर्ट करें. इससे यह पक्का होता है कि AlloyDB Admin क्लाइंट के लिए ज़रूरी protobuf-java (4.x) और gRPC के नए वर्शन को, फ़्रेमवर्क बीओएम से मैनेज किए जाने वाले पुराने वर्शन के मुकाबले प्राथमिकता मिले.

Micronaut कॉन्फ़िगरेशन (HikariCP के साथ application.yml)

किसी Micronaut ऐप्लिकेशन (micronaut-jdbc-hikari) में, com.google.cloud:alloydb-jdbc-connector:1.4.0 जोड़ें और 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

GraalVM नेटिव इमेज के लिए कनेक्टर को रजिस्टर करना

अपने ऐप्लिकेशन को GraalVM नेटिव इमेज (Spring Boot 3+, Quarkus या Micronaut के साथ) में कंपाइल करते समय, एक अहम जानकारी का ध्यान रखना ज़रूरी है: रिफ़्लेक्शन.

PostgreSQL JDBC ड्राइवर, रिफ़्लेक्शन का इस्तेमाल करके क्लास के नाम के हिसाब से, com.google.cloud.alloydb.SocketFactory को डाइनैमिक तौर पर इंस्टैंशिएट करता है. नेटिव कंपाइलेशन के दौरान, GraalVM के स्टैटिक विश्लेषण को क्लास हटाने से रोकने के लिए, इसे साफ़ तौर पर रजिस्टर करें:

• Spring Boot 3+: अपने मुख्य ऐप्लिकेशन या @Configuration क्लास में @RegisterReflectionForBinding(com.google.cloud.alloydb.SocketFactory.class) जोड़ें:

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

• Quarkus: अपनी मुख्य क्लास या सीडीआई बीन में @RegisterForReflection(targets = com.google.cloud.alloydb.SocketFactory.class) जोड़ें:

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

6. IAM और कनेक्टिविटी से जुड़ी सामान्य समस्याएं हल करना

अगर आपको FATAL: password authentication failed for user या AlloyDB IAM authentication failed गड़बड़ी का मैसेज मिलता है, तो इन चार चीज़ों की जांच करें:

1. सेवा खाते के डेटाबेस के उपयोगकर्ता नामों से .gserviceaccount.com को हटाएं

IAM की पुष्टि की सुविधा के काम न करने की सबसे आम वजह, सेवा खाते के पूरे ईमेल पते को डेटाबेस के उपयोगकर्ता नाम के तौर पर पास करना है. AlloyDB, IAM डेटाबेस के उपयोगकर्ता नामों को प्रिंसिपल टाइप के आधार पर अलग-अलग फ़ॉर्मैट में दिखाता है:

• IAM सेवा खातों के लिए (.gserviceaccount.com को हटाएं): अगर आपके Google Cloud सेवा खाते का ईमेल पता java-alloydb-connector@.iam.gserviceaccount.com है, तो आपको .gserviceaccount.com सफ़िक्स को हटाना होगा. साथ ही, अपने JDBC/AlloyDB डेटाबेस का उपयोगकर्ता नाम java-alloydb-connector@.iam पर सेट करना होगा.
• आईएएम उपयोगकर्ता खातों या ग्रुप के लिए (पूरा ईमेल पता रखें): अगर Google Workspace या Cloud Identity के उपयोगकर्ता के तौर पर आपकी पुष्टि की जा रही है, तो अपने पूरे ईमेल पते का इस्तेमाल करें. इसमें कोई बदलाव न करें (उदाहरण के लिए, ).

2. पुष्टि करें कि डेटाबेस उपयोगकर्ता को कैसे बनाया गया था

क्या आपने उपयोगकर्ता को gcloud alloydb users create --type=IAM_BASED (या Console/Terraform) के ज़रिए रजिस्टर किया है? रॉ एसक्यूएल CREATE USER का इस्तेमाल करके उपयोगकर्ता बनाने पर, आईएएम की मदद से पुष्टि करने की सुविधा काम नहीं करेगी. इसकी वजह यह है कि AlloyDB, GRANT alloydbiamuser को कंट्रोल प्लेन तक सीमित रखता है.

3. अपने चालू एडीसी खाते की पहचान की पुष्टि करना

पक्का करें कि जिस एनवायरमेंट में Java प्रोसेस चल रही है उसकी पुष्टि, टारगेट आईएएम प्रिंसिपल के तौर पर की गई हो:

• लोकल वर्कस्टेशन (सेवा खाते के तौर पर कनेक्ट करना): gcloud auth application-default login --impersonate-service-account=java-alloydb-connector@.iam.gserviceaccount.com चलाएं, ताकि एडीसी आपके निजी ईमेल के बजाय सेवा खाते के लिए टोकन जनरेट करे.
• Cloud Run / GKE: पुष्टि करें कि सेवा खाता, वर्कलोड से जुड़ा हो. साथ ही, उसके पास roles/alloydb.client और roles/serviceusage.serviceUsageConsumer, दोनों अनुमतियां हों.

4. आईएएम प्रोपेगेशन और नेटवर्क रूटिंग के लिए खाता

• IAM प्रोपेगेशन में लगने वाला समय: IAM नीति की बाइंडिंग को लागू होने में 60 से 120 सेकंड लग सकते हैं. अगर आपने अभी-अभी सेवा खाता बनाया है या भूमिका बाइंडिंग की है, तो एक मिनट इंतज़ार करें और फिर से कोशिश करें.
• वीपीसी नेटवर्क ऐक्सेस: डिफ़ॉल्ट रूप से, AlloyDB Java कनेक्टर, इंस्टेंस के PRIVATE आईपी से कनेक्ट होता है. अगर आपका ऐप्लिकेशन Cloud Run पर चलता है, तो Direct VPC Egress को कॉन्फ़िगर करें (सर्वर के बिना वीपीसी ऐक्सेस करने की सुविधा के लेगसी कनेक्टर की तुलना में, इंतज़ार का समय और लागत कम करने के लिए सुझाया गया है) या Private Service Connect (PSC) के ज़रिए कनेक्ट करें. अगर वीपीसी के बाहर किसी लोकल मशीन से कनेक्ट किया जा रहा है, तो इंस्टेंस पर सार्वजनिक आईपी चालू करें और alloydbIpType=PUBLIC पास करें.

7. व्यवस्थित करें

अपने Google Cloud खाते पर बेवजह के शुल्क लगने से बचने और इस कोडलैब के दौरान बनाई गई आईएएम आइडेंटिटी हटाने के लिए, यहां दिए गए संसाधनों को मिटाएं.

1. AlloyDB IAM डेटाबेस उपयोगकर्ता और सेवा खाते को हटाना

अपने AlloyDB क्लस्टर से IAM डेटाबेस उपयोगकर्ता को मिटाएं और सेवा खाते को हटाएं:

# 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. लोकल ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल रीसेट करना

अगर आपने लोकल एडीसी इंपर्सनेशन को कॉन्फ़िगर किया है, तो अपने लोकल क्रेडेंशियल को डिफ़ॉल्ट उपयोगकर्ता पहचान पर रीसेट करें:

gcloud auth application-default login

3. (ज़रूरी नहीं) AlloyDB क्लस्टर को मिटाना

चेतावनी: AlloyDB क्लस्टर को मिटाने से, उसमें मौजूद सभी इंस्टेंस और डेटाबेस हमेशा के लिए मिट जाते हैं. अगर आपने सिर्फ़ इस कोडलैब के लिए एक टेस्ट क्लस्टर बनाया है, तो यहां दिया गया कमांड चलाएं.

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

8. बधाई हो

आपने कोडलैब पूरा कर लिया है. साथ ही, Java से AlloyDB for PostgreSQL के लिए सुरक्षित और पासवर्डलेस कनेक्टिविटी सेट अप कर ली है!

आपने क्या-क्या हासिल किया है

1. आईएएम डेटाबेस ऑथेंटिकेशन को कॉन्फ़िगर किया गया: कम से कम अधिकार वाला सेवा खाता बनाया गया, alloydb.iam_authentication=on को चालू किया गया, AlloyDB क्लस्टर पर आईएएम उपयोगकर्ता को रजिस्टर किया गया, और PostgreSQL टेबल की अनुमतियां दी गईं.
2. Plain JDBC और HikariCP के साथ कनेक्ट किया गया: HikariConfig को com.google.cloud.alloydb.SocketFactory के साथ कॉन्फ़िगर किया गया है, ताकि mTLS 1.3 एन्क्रिप्शन, आईएएम टोकन रीफ़्रेश, और डाइनैमिक आईपी रिज़ॉल्यूशन की सुविधा अपने-आप काम करे.
3. इंटिग्रेट किए गए क्लाउड-नेटिव फ़्रेमवर्क: Spring Boot, Quarkus (Agroal), और Micronaut (HikariCP) को कॉन्फ़िगर किया गया. इसके लिए, कस्टम कनेक्शन-पूल बॉयलरप्लेट की ज़रूरत नहीं पड़ी. साथ ही, GraalVM नेटिव इमेज के लिए रिफ़्लेक्शन हिंट भी दिए गए.
4. आईएएम से जुड़ी समस्याओं को हल करने में महारत हासिल की: उपयोगकर्ता नाम के फ़ॉर्मैट, एडीसी के नाम पर काम करने, और वीपीसी रूटिंग से जुड़ी समस्याओं का पता लगाने का तरीका सीखा.

ज़्यादा जानें

• AlloyDB for PostgreSQL के दस्तावेज़
• AlloyDB Java Connector GitHub रिपॉज़िटरी
• AlloyDB कनेक्शन के बारे में खास जानकारी
• AlloyDB Express के बारे में खास जानकारी
• AlloyDB Omni का दस्तावेज़