快速入門:搭配 適用於 PostgreSQL 的 Azure 資料庫 使用 Java 和 JDBC

適用於:適用於 PostgreSQL 的 Azure 資料庫 - 單一伺服器

重要

適用於 PostgreSQL 的 Azure 資料庫 - 單一伺服器位於淘汰路徑上。 強烈建議您升級至 適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器。 如需移轉至 適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器的詳細資訊,請參閱單一伺服器 適用於 PostgreSQL 的 Azure 資料庫 發生什麼事?

本文示範如何建立使用 Java 和 JDBC 來儲存和擷取 適用於 PostgreSQL 的 Azure 資料庫 資訊的範例應用程式。

JDBC 是用來連線到傳統關聯式資料庫的標準 JAVA API。

在本文中,我們將包含兩種驗證方法:Microsoft Entra 驗證和 PostgreSQL 驗證。 [無密碼] 索引標籤會顯示 Microsoft Entra 驗證,而 [密碼] 索引標籤會顯示 PostgreSQL 驗證。

Microsoft Entra 驗證是使用 Microsoft Entra 識別碼中定義的身分識別連線到 適用於 PostgreSQL 的 Azure 資料庫 的機制。 透過 Microsoft Entra 驗證,您可以在集中的位置管理資料庫使用者的身分識別和其他 Microsoft 服務,從而簡化權限管理。

PostgreSQL 驗證會使用儲存在 PostgreSQL 中的帳戶。 如果您選擇使用密碼作為帳戶的認證,則這些認證會儲存在 user 資料表中。 因為這些密碼會儲存在PostgreSQL中,因此您必須自行管理密碼輪替。

必要條件

準備工作環境

首先,設定一些環境變數。 在 Azure Cloud Shell 中,執行下列命令:

export AZ_RESOURCE_GROUP=database-workshop
export AZ_DATABASE_SERVER_NAME=<YOUR_DATABASE_SERVER_NAME>
export AZ_DATABASE_NAME=demo
export AZ_LOCATION=<YOUR_AZURE_REGION>
export AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME=<YOUR_POSTGRESQL_AD_NON_ADMIN_USERNAME>
export AZ_LOCAL_IP_ADDRESS=<YOUR_LOCAL_IP_ADDRESS>
export CURRENT_USERNAME=$(az ad signed-in-user show --query userPrincipalName -o tsv)
export CURRENT_USER_OBJECTID=$(az ad signed-in-user show --query id -o tsv)

將預留位置取代為下列值,本文通篇都將使用這些值:

  • <YOUR_DATABASE_SERVER_NAME>:P ostgreSQL 伺服器的名稱,在 Azure 中應該是唯一的。
  • <YOUR_AZURE_REGION>:您將使用的 Azure 區域。 根據預設,您可以使用 eastus,但建議您將區域設定為您居住地附近的位置。 您可以輸入 az account list-locations 來查看可用區域的完整清單。
  • <YOUR_POSTGRESQL_AD_NON_ADMIN_USERNAME>:P ostgreSQL 資料庫伺服器的用戶名稱。 請確定使用者名稱是 Microsoft Entra 租使用者中的有效使用者。
  • <YOUR_LOCAL_IP_ADDRESS>:本機計算機的IP位址,您將從中執行 Spring Boot 應用程式。 找到它的一個便利方式是開啟 whatismyip.akamai.com

重要

設定 <YOUR_POSTGRESQL_AD_NON_ADMIN_USERNAME>時,使用者名稱必須已存在於您的 Microsoft Entra 租使用者中,否則您將無法在資料庫中建立 Microsoft Entra 使用者。

接下來,使用下列命令建立資源群組:

az group create \
    --name $AZ_RESOURCE_GROUP \
    --location $AZ_LOCATION \
    --output tsv

建立 適用於 PostgreSQL 的 Azure 資料庫 實例

下列各節說明如何建立及設定您的資料庫實例。

建立 PostgreSQL 伺服器並設定系統管理員使用者

您建立的第一件事是具有系統管理員使用者的受控 PostgreSQL 伺服器。

注意

您可以在使用 Azure 入口網站 建立 適用於 PostgreSQL 的 Azure 資料庫 伺服器中,閱讀建立 PostgreSQL 伺服器的詳細資訊。

如果您正在使用 Azure CLI,請執行下列命令來確定其具有足夠的權限:

az login --scope https://graph.microsoft.com/.default

然後執行下列命令來建立伺服器:

az postgres server create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --location $AZ_LOCATION \
    --sku-name B_Gen5_1 \
    --storage-size 5120 \
    --output tsv

現在執行下列命令來設定 Microsoft Entra 系統管理員使用者:

az postgres server ad-admin create \
    --resource-group $AZ_RESOURCE_GROUP \
    --server-name $AZ_DATABASE_SERVER_NAME \
    --display-name $CURRENT_USERNAME \
    --object-id $CURRENT_USER_OBJECTID

重要

設定系統管理員時,會將新的使用者新增至具有完整系統管理員許可權的 適用於 PostgreSQL 的 Azure 資料庫 伺服器。 每個 PostgreSQL 伺服器只能建立一個 Microsoft Entra 系統管理員,而另一個伺服器的選取專案將會覆寫為伺服器設定的現有 Microsoft Entra 管理員。

此命令會建立小型 PostgreSQL 伺服器,並將 Active Directory 系統管理員設定為已登入的使用者。

設定 PostgreSQL 伺服器的防火牆規則

適用於 PostgreSQL 的 Azure 資料庫 實例預設會受到保護。 它們具有不允許任何連入連線的防火牆。 若要使用資料庫,必須新增防火牆規則,以允許本機 IP 位址存取資料庫伺服器。

由於您已在本文開頭設定本機 IP 位址,因此您可以執行下列命令來開啟伺服器的防火牆:

az postgres server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --server $AZ_DATABASE_SERVER_NAME \
    --start-ip-address $AZ_LOCAL_IP_ADDRESS \
    --end-ip-address $AZ_LOCAL_IP_ADDRESS \
    --output tsv

如果您要從 Windows 電腦上的 Windows 子系統 Linux 版 (WSL) 連線到 PostgreSQL 伺服器,您必須將 WSL 主機標識元新增至防火牆。

在 WSL 中執行下列命令,以取得您主機電腦的 IP 位址:

cat /etc/resolv.conf

複製 nameserver 一詞後面的 IP 位址,然後使用下列命令來設定 WSL IP 位址的環境變數:

AZ_WSL_IP_ADDRESS=<the-copied-IP-address>

然後,使用下列命令,將伺服器的防火牆開啟至 WSL 應用程式:

az postgres server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --server $AZ_DATABASE_SERVER_NAME \
    --start-ip-address $AZ_WSL_IP_ADDRESS \
    --end-ip-address $AZ_WSL_IP_ADDRESS \
    --output tsv

設定 PostgreSQL 資料庫

您先前建立的 PostgreSQL 伺服器是空的。 使用下列命令來建立新的資料庫。

az postgres db create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_NAME \
    --server-name $AZ_DATABASE_SERVER_NAME \
    --output tsv

建立 PostgreSQL 非系統管理員使用者並授與許可權

接下來,建立非系統管理員使用者,並將所有許可權授與資料庫。

注意

您可以在建立 適用於 PostgreSQL 的 Azure 資料庫 中的使用者中,閱讀有關建立 PostgreSQL 用戶的詳細資訊。

建立名為 create_ad_user.sql 的 SQL 指令碼,以建立非管理使用者。 新增下列內容,並將其儲存在本地:

cat << EOF > create_ad_user.sql
SET aad_validate_oids_in_tenant = off;
CREATE ROLE "$AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME" WITH LOGIN IN ROLE azure_ad_user;
GRANT ALL PRIVILEGES ON DATABASE $AZ_DATABASE_NAME TO "$AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME";
EOF

然後,使用下列命令來執行 SQL 指令碼,以建立 Microsoft Entra 非管理使用者:

psql "host=$AZ_DATABASE_SERVER_NAME.postgres.database.azure.com user=$CURRENT_USERNAME@$AZ_DATABASE_SERVER_NAME dbname=$AZ_DATABASE_NAME port=5432 password=$(az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken) sslmode=require" < create_ad_user.sql

現在,使用下列命令來移除暫存 SQL 指令檔:

rm create_ad_user.sql

建立新的 Java 專案

使用您慣用的 IDE,使用 Java 8 或更新版本建立新的 Java 專案,並在其根目錄中新增 具有下列內容的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>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>

    <properties>
        <java.version>1.8</java.version>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>
      <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.3.6</version>
      </dependency>
      <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity-extensions</artifactId>
        <version>1.0.0</version>
      </dependency>
    </dependencies>
</project>

此檔案是 Apache Maven 檔案,可將您的項目設定為使用 Java 8 和最新的適用於 Java 的 PostgreSQL 驅動程式。

準備組態檔以連線到 適用於 PostgreSQL 的 Azure 資料庫

建立 src/main/resources/application.properties 檔案,然後新增下列內容:

cat << EOF > src/main/resources/application.properties
url=jdbc:postgresql://${AZ_DATABASE_SERVER_NAME}.postgres.database.azure.com:5432/${AZ_DATABASE_NAME}?sslmode=require&authenticationPluginClassName=com.azure.identity.extensions.jdbc.postgresql.AzurePostgresqlAuthenticationPlugin
user=${AZ_POSTGRESQL_AD_NON_ADMIN_USERNAME}@${AZ_DATABASE_SERVER_NAME}
EOF

注意

組態屬性 url?sslmode=require 附加,以告知 JDBC 驅動程式在連線到資料庫時使用 TLS(傳輸層安全性)。 使用 TLS 是強制 適用於 PostgreSQL 的 Azure 資料庫,而且這是良好的安全性做法。

建立 SQL 檔案以產生資料庫結構描述

您將使用 src/main/resources/schema.sql 檔案來建立資料庫架構。 建立該檔案,然後新增下列內容:

cat << EOF > src/main/resources/schema.sql
DROP TABLE IF EXISTS todo;
CREATE TABLE todo (id SERIAL PRIMARY KEY, description VARCHAR(255), details VARCHAR(4096), done BOOLEAN);
EOF

編碼應用程式

連線至資料庫

接下來,新增將使用 JDBC 的 Java 程式代碼來儲存和擷取 PostgreSQL 伺服器的數據。

建立 src/main/java/DemoApplication.java 檔案,然後新增下列內容:

package com.example.demo;

import java.sql.*;
import java.util.*;
import java.util.logging.Logger;

public class DemoApplication {

    private static final Logger log;

    static {
        System.setProperty("java.util.logging.SimpleFormatter.format", "[%4$-7s] %5$s %n");
        log =Logger.getLogger(DemoApplication.class.getName());
    }

    public static void main(String[] args) throws Exception {
        log.info("Loading application properties");
        Properties properties = new Properties();
        properties.load(DemoApplication.class.getClassLoader().getResourceAsStream("application.properties"));

        log.info("Connecting to the database");
        Connection connection = DriverManager.getConnection(properties.getProperty("url"), properties);
        log.info("Database connection test: " + connection.getCatalog());

        log.info("Create database schema");
        Scanner scanner = new Scanner(DemoApplication.class.getClassLoader().getResourceAsStream("schema.sql"));
        Statement statement = connection.createStatement();
        while (scanner.hasNextLine()) {
            statement.execute(scanner.nextLine());
        }

        /* Prepare for data processing in the PostgreSQL server.
        Todo todo = new Todo(1L, "configuration", "congratulations, you have set up JDBC correctly!", true);
        insertData(todo, connection);
        todo = readData(connection);
        todo.setDetails("congratulations, you have updated data!");
        updateData(todo, connection);
        deleteData(todo, connection);
        */

        log.info("Closing database connection");
        connection.close();
    }
}

此 Java 程式代碼會使用 您稍早建立的 application.propertiesschema.sql 檔案,以連線到 PostgreSQL 伺服器,並建立將儲存數據的架構。

在此檔案中,您可以看到我們已加上批注的方法,以插入、讀取、更新和刪除數據。 您將在本文的其餘部分撰寫這些方法的程序代碼,而且您可以一個接一個地取消批注。

注意

資料庫認證會儲存在 user application.properties 檔案的 password 屬性中。 執行 DriverManager.getConnection(properties.getProperty("url"), properties); 時會使用這些認證,因為屬性檔案會作為引數傳遞。

您現在可以使用慣用的工具來執行此主要類別:

  • 使用 IDE 時,您應該能夠以滑鼠右鍵按一下 DemoApplication 類別,然後加以執行。
  • 使用 Maven,您可以使用下列命令來執行應用程式: mvn exec:java -Dexec.mainClass="com.example.demo.DemoApplication"

應用程式應該連線到 適用於 PostgreSQL 的 Azure 資料庫、建立資料庫架構,然後關閉連線,如控制台記錄中所見:

[INFO   ] Loading application properties 
[INFO   ] Connecting to the database 
[INFO   ] Database connection test: demo 
[INFO   ] Create database schema 
[INFO   ] Closing database connection 

建立領域類別

DemoApplication 類別旁建立新的 Todo Java 類別,並新增下列程式碼:

package com.example.demo;

public class Todo {

    private Long id;
    private String description;
    private String details;
    private boolean done;

    public Todo() {
    }

    public Todo(Long id, String description, String details, boolean done) {
        this.id = id;
        this.description = description;
        this.details = details;
        this.done = done;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getDetails() {
        return details;
    }

    public void setDetails(String details) {
        this.details = details;
    }

    public boolean isDone() {
        return done;
    }

    public void setDone(boolean done) {
        this.done = done;
    }

    @Override
    public String toString() {
        return "Todo{" +
                "id=" + id +
                ", description='" + description + '\'' +
                ", details='" + details + '\'' +
                ", done=" + done +
                '}';
    }
}

這個類別是在您執行 schema.sql 指令碼時建立的 todo 資料表中對應的領域模型。

將數據插入 適用於 PostgreSQL 的 Azure 資料庫

在 src/main/java/DemoApplication.jav 檔案中,在 main 方法後面新增下列方法,以將資料插入資料庫:

private static void insertData(Todo todo, Connection connection) throws SQLException {
    log.info("Insert data");
    PreparedStatement insertStatement = connection
            .prepareStatement("INSERT INTO todo (id, description, details, done) VALUES (?, ?, ?, ?);");

    insertStatement.setLong(1, todo.getId());
    insertStatement.setString(2, todo.getDescription());
    insertStatement.setString(3, todo.getDetails());
    insertStatement.setBoolean(4, todo.isDone());
    insertStatement.executeUpdate();
}

您現在可以取消 main 方法中下列兩行的註解:

Todo todo = new Todo(1L, "configuration", "congratulations, you have set up JDBC correctly!", true);
insertData(todo, connection);

執行主要類別現在應該會產生下列輸出:

[INFO   ] Loading application properties 
[INFO   ] Connecting to the database 
[INFO   ] Database connection test: demo 
[INFO   ] Create database schema 
[INFO   ] Insert data 
[INFO   ] Closing database connection

從 適用於 PostgreSQL 的 Azure 資料庫 讀取數據

若要驗證程式代碼是否正常運作,請讀取您先前插入的數據。

在 src/main/java/DemoApplication.java 檔案中的 insertData 方法後面新增下列方法,以讀取資料庫中的資料:

private static Todo readData(Connection connection) throws SQLException {
    log.info("Read data");
    PreparedStatement readStatement = connection.prepareStatement("SELECT * FROM todo;");
    ResultSet resultSet = readStatement.executeQuery();
    if (!resultSet.next()) {
        log.info("There is no data in the database!");
        return null;
    }
    Todo todo = new Todo();
    todo.setId(resultSet.getLong("id"));
    todo.setDescription(resultSet.getString("description"));
    todo.setDetails(resultSet.getString("details"));
    todo.setDone(resultSet.getBoolean("done"));
    log.info("Data read from the database: " + todo.toString());
    return todo;
}

您現在可以取消 main 方法中下列行的註解:

todo = readData(connection);

執行主要類別現在應該會產生下列輸出:

[INFO   ] Loading application properties 
[INFO   ] Connecting to the database 
[INFO   ] Database connection test: demo 
[INFO   ] Create database schema 
[INFO   ] Insert data 
[INFO   ] Read data 
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have set up JDBC correctly!', done=true} 
[INFO   ] Closing database connection 

更新 適用於 PostgreSQL 的 Azure 資料庫 中的數據

接下來,更新您先前插入的資料。

在 src/main/java/DemoApplication.java 檔案中的 readData 方法後面新增下列方法,以更新資料庫中的資料:

private static void updateData(Todo todo, Connection connection) throws SQLException {
    log.info("Update data");
    PreparedStatement updateStatement = connection
            .prepareStatement("UPDATE todo SET description = ?, details = ?, done = ? WHERE id = ?;");

    updateStatement.setString(1, todo.getDescription());
    updateStatement.setString(2, todo.getDetails());
    updateStatement.setBoolean(3, todo.isDone());
    updateStatement.setLong(4, todo.getId());
    updateStatement.executeUpdate();
    readData(connection);
}

您現在可以取消 main 方法中下列兩行的註解:

todo.setDetails("congratulations, you have updated data!");
updateData(todo, connection);

執行主要類別現在應該會產生下列輸出:

[INFO   ] Loading application properties 
[INFO   ] Connecting to the database 
[INFO   ] Database connection test: demo 
[INFO   ] Create database schema 
[INFO   ] Insert data 
[INFO   ] Read data 
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have set up JDBC correctly!', done=true} 
[INFO   ] Update data 
[INFO   ] Read data 
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have updated data!', done=true} 
[INFO   ] Closing database connection 

刪除 適用於 PostgreSQL 的 Azure 資料庫中的數據

最後,刪除您先前插入的資料。

在 src/main/java/DemoApplication.java 檔案中的 updateData 方法後面新增下列方法,以刪除資料庫中的資料:

private static void deleteData(Todo todo, Connection connection) throws SQLException {
    log.info("Delete data");
    PreparedStatement deleteStatement = connection.prepareStatement("DELETE FROM todo WHERE id = ?;");
    deleteStatement.setLong(1, todo.getId());
    deleteStatement.executeUpdate();
    readData(connection);
}

您現在可以取消 main 方法中下列行的註解:

deleteData(todo, connection);

執行主要類別現在應該會產生下列輸出:

[INFO   ] Loading application properties 
[INFO   ] Connecting to the database 
[INFO   ] Database connection test: demo 
[INFO   ] Create database schema 
[INFO   ] Insert data 
[INFO   ] Read data 
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have set up JDBC correctly!', done=true} 
[INFO   ] Update data 
[INFO   ] Read data 
[INFO   ] Data read from the database: Todo{id=1, description='configuration', details='congratulations, you have updated data!', done=true} 
[INFO   ] Delete data 
[INFO   ] Read data 
[INFO   ] There is no data in the database! 
[INFO   ] Closing database connection 

清除資源

恭喜! 您已建立使用 JDBC 來儲存和擷取 適用於 PostgreSQL 的 Azure 資料庫 資料的 Java 應用程式。

若要清除在此快速入門期間使用的所有資源,請使用下列命令刪除資源群組:

az group delete \
    --name $AZ_RESOURCE_GROUP \
    --yes

下一步