搭配適用於 PostgreSQL 的 Azure 資料庫使用 Spring Data JPA

發行項
08/28/2024

本教學課程示範如何使用 Spring Data JPA 將數據儲存在適用於 PostgreSQL 的 Azure 資料庫。

Java 持續性 API （JPA）是對象關係型對應的標準 Java API。

在本教學課程中，我們包含兩種驗證方法：Microsoft Entra 驗證和 PostgreSQL 驗證。 [無密碼] 索引標籤會顯示 Microsoft Entra 驗證，而 [密碼] 索引標籤則會顯示 PostgreSQL 驗證。

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

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

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
Java Development Kit （JDK）版本 8 或更高版本。
Apache Maven。
Azure CLI。

PostgreSQL 命令行用戶端。
如果您沒有 Spring Boot 應用程式，請使用 Spring Initializr 建立 Maven 專案。請務必選取 Maven 專案，然後在 [相依性] 底下新增 Spring Web、Spring Data JDBC 和 PostgreSQL 驅動程式相依性，然後選取 [Java 第 8 版] 或更新版本。

如果您沒有實例，請建立名為 postgresqlflexibletest 適用於 PostgreSQL 的 Azure 資料庫彈性伺服器實例，以及名為demo的資料庫。如需指示，請參閱快速入門：在 Azure 入口網站中建立適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器。

重要

若要使用無密碼連線，請為適用於 PostgreSQL 的 Azure 資料庫彈性伺服器實例設定 Microsoft Entra 系統管理員使用者。如需詳細資訊，請參閱在適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器中管理Microsoft Entra 角色。

請參閱範例應用程式

在本教學課程中，您將撰寫範例應用程式的程序代碼。如果您想要更快速地執行，此應用程式已編碼，且可在取得 https://github.com/Azure-Samples/quickstart-spring-data-jpa-postgresql。

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

適用於 PostgreSQL 的 Azure 資料庫執行個體依預設會受到保護。其防火牆不允許任何連入連線。

若要能夠使用您的資料庫，請開啟伺服器的防火牆，以允許本機 IP 位址存取資料庫伺服器。如需詳細資訊，請參閱適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器的防火牆規則。

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

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

接下來，建立非系統管理員使用者，並授與資料庫的所有權限。

無密碼 (建議)
密碼

您可以使用下列方法來建立使用無密碼連線的非系統管理員使用者。

服務連接器 (建議)
手動設定

使用下列命令來安裝 Azure CLI 的 Service Connector 無密碼擴充功能：
```
 az extension add --name serviceconnector-passwordless --upgrade
```

使用下列命令來建立 Microsoft Entra 非系統管理員使用者：

  az connection create postgres-flexible \
       --resource-group <your_resource_group_name> \
       --connection postgres_conn \
       --target-resource-group <your_resource_group_name> \
       --server postgresqlflexibletest \
       --database demo \
       --user-account \
       --query authInfo.userName \
       --output tsv

當命令完成時，記下主控台輸出中的用戶名稱。

重要

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

cat << EOF > create_ad_user.sql
select * from pgaadauth_create_principal('<your_postgresql_ad_non_admin_username>', false, false);
EOF

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

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

提示

若要使用 Microsoft Entra 驗證來連線到適用於 PostgreSQL 的 Azure 資料庫，您必須使用您設定的 Microsoft Entra 系統管理員使用者登入，然後取得存取令牌作為密碼。如需詳細資訊，請參閱使用 Microsoft Entra ID 搭配適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器進行驗證。

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

cat << EOF > create_user.sql
CREATE ROLE "<your_postgresql_non_admin_username>" WITH LOGIN PASSWORD '<your_postgresql_non_admin_password>';
GRANT ALL PRIVILEGES ON DATABASE demo TO "<your_postgresql_non_admin_username>";
EOF

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

psql "host=postgresqlflexibletest.postgres.database.azure.com user=<your_postgresql_admin_username> dbname=demo port=5432 password=<your_postgresql_admin_password> sslmode=require" < create_user.sql

注意

如需詳細資訊，請參閱在適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器中建立使用者。

從適用於 PostgreSQL 的 Azure 資料庫儲存數據

現在您已擁有適用於 PostgreSQL 的 Azure 資料庫彈性伺服器實例，您可以使用 Spring Cloud Azure 來儲存數據。

若要安裝 Spring Cloud Azure Starter JDBC PostgreSQL 模組，請將下列相依性新增至您的 pom.xml 檔案：

Spring Cloud Azure 材料帳單（BOM）：
```
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>5.19.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```
注意

如果您使用 Spring Boot 2.x，請務必將 spring-cloud-azure-dependencies 版本設定為 4.19.0。此材料帳單（BOM）應該在<dependencyManagement>pom.xml檔案的區段中設定。這可確保所有 Spring Cloud Azure 相依性都使用相同的版本。如需此 BOM 所用版本的詳細資訊，請參閱應該使用哪個版本的 Spring Cloud Azure。

Spring Cloud Azure Starter JDBC PostgreSQL 成品：

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-jdbc-postgresql</artifactId>
</dependency>

注意

自版本 4.5.0以來，已支援無密碼連線。

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫

若要使用 Spring Data JPA 從適用於 PostgreSQL 的 Azure 資料庫儲存數據，請遵循下列步驟來設定應用程式：

將下列屬性新增至 application.properties 組態檔，以設定適用於 PostgreSQL 的 Azure 資料庫認證。

無密碼 (建議)
密碼

logging.level.org.hibernate.SQL=DEBUG

spring.datasource.url=jdbc:postgresql://postgresqlflexibletest.postgres.database.azure.com:5432/demo?sslmode=require
spring.datasource.username=<your_postgresql_ad_non_admin_username>
spring.datasource.azure.passwordless-enabled=true

spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

logging.level.org.hibernate.SQL=DEBUG

spring.datasource.url=jdbc:postgresql://postgresqlflexibletest.postgres.database.azure.com:5432/demo?sslmode=require
spring.datasource.username=<your_postgresql_non_admin_username>
spring.datasource.password=<your_postgresql_non_admin_password>

spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

如果您沒有，請建立名為的單一伺服器實例和名為 postgresqlsingletest demo的資料庫適用於 PostgreSQL 的 Azure 資料庫。如需指示，請參閱快速入門：使用 Azure 入口網站建立適用於 PostgreSQL 的 Azure 資料庫伺服器。

重要

若要使用無密碼連線，請為您的適用於 PostgreSQL 的 Azure 資料庫單一伺服器實例設定 Microsoft Entra 系統管理員使用者。如需詳細資訊，請參閱使用 Microsoft Entra ID 進行 PostgreSQL 驗證。

請參閱範例應用程式

在本文中，您將撰寫範例應用程式的程序代碼。如果您想要更快速地執行，此應用程式已編碼，且可在取得 https://github.com/Azure-Samples/quickstart-spring-data-jpa-postgresql。

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

適用於 PostgreSQL 的 Azure 資料庫執行個體依預設會受到保護。其防火牆不允許任何連入連線。

若要能夠使用您的資料庫，請開啟伺服器的防火牆，以允許本機 IP 位址存取資料庫伺服器。如需詳細資訊，請參閱使用 Azure 入口網站建立和管理適用於 PostgreSQL 的 Azure 資料庫 - 單一伺服器的防火牆規則。

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

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

接下來，建立非系統管理員使用者，並授與資料庫的所有權限。

無密碼 (建議)
密碼

您可以使用下列方法來建立使用無密碼連線的非系統管理員使用者。

服務連接器 (建議)
手動設定

使用下列命令來安裝 Azure CLI 的 Service Connector 無密碼擴充功能：
```
 az extension add --name serviceconnector-passwordless --upgrade
```

使用下列命令來建立 Microsoft Entra 非系統管理員使用者：

  az connection create postgres \
       --resource-group <your_resource_group_name> \
       --connection postgres_conn \
       --target-resource-group <your_resource_group_name> \
       --server postgresqlsingletest \
       --database demo \
       --user-account \
       --query authInfo.userName \
       --output tsv

當命令完成時，記下主控台輸出中的用戶名稱。

重要

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

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

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

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

提示

若要使用 Microsoft Entra 驗證來連線到適用於 PostgreSQL 的 Azure 資料庫，您必須使用您設定的 Microsoft Entra 系統管理員使用者登入，然後取得存取令牌作為密碼。如需詳細資訊，請參閱使用 Microsoft Entra ID 進行 PostgreSQL 驗證。

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

cat << EOF > create_user.sql
CREATE ROLE "<your_postgresql_non_admin_username>" WITH LOGIN PASSWORD '<your_postgresql_non_admin_password>';
GRANT ALL PRIVILEGES ON DATABASE demo TO "<your_postgresql_non_admin_username>";
EOF

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

psql "host=postgresqlsingletest.postgres.database.azure.com user=<your_postgresql_admin_username>@postgresqlsingletest dbname=demo port=5432 password=<your_postgresql_admin_password> sslmode=require" < create_user.sql

注意

如需建立 PostgreSQL 使用者的更多詳細資訊，請參閱在適用於 PostgreSQL 的 Azure 資料庫中建立使用者。

從適用於 PostgreSQL 的 Azure 資料庫儲存數據

現在您已擁有適用於 PostgreSQL 的 Azure 資料庫單一伺服器實例，您可以使用 Spring Cloud Azure 來儲存數據。

若要安裝 Spring Cloud Azure Starter JDBC PostgreSQL 模組，請將下列相依性新增至您的 pom.xml 檔案：

Spring Cloud Azure 材料帳單（BOM）：
```
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>5.19.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```
注意

如果您使用 Spring Boot 2.x，請務必將 spring-cloud-azure-dependencies 版本設定為 4.19.0。此材料帳單（BOM）應該在<dependencyManagement>pom.xml檔案的區段中設定。這可確保所有 Spring Cloud Azure 相依性都使用相同的版本。如需此 BOM 所用版本的詳細資訊，請參閱應該使用哪個版本的 Spring Cloud Azure。

Spring Cloud Azure Starter JDBC PostgreSQL 成品：

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-jdbc-postgresql</artifactId>
</dependency>

注意

自版本 4.5.0以來，已支援無密碼連線。

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫

若要使用 Spring Data JPA 從適用於 PostgreSQL 的 Azure 資料庫儲存數據，請遵循下列步驟來設定應用程式：

將下列屬性新增至 application.properties 組態檔，以設定適用於 PostgreSQL 的 Azure 資料庫認證。

無密碼 (建議)
密碼

logging.level.org.hibernate.SQL=DEBUG

spring.datasource.url=jdbc:postgresql://postgresqlsingletest.postgres.database.azure.com:5432/demo?sslmode=require
spring.datasource.username=<your_postgresql_ad_non_admin_username>@postgresqlsingletest
spring.datasource.azure.passwordless-enabled=true

spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

logging.level.org.hibernate.SQL=DEBUG

spring.datasource.url=jdbc:postgresql://postgresqlsingletest.postgres.database.azure.com:5432/demo?sslmode=require
spring.datasource.username=<your_postgresql_non_admin_username>@postgresqlsingletest
spring.datasource.password=<your_postgresql_non_admin_password>

spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

建立新的 Todo Java 類別。這個類別是對應至 JPA 自動建立之數據表的 todo 網域模型。下列程式代碼會 getters 忽略和 setters 方法。

package com.example.demo;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

@Entity
public class Todo {

    public Todo() {
    }

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

    @Id
    @GeneratedValue
    private Long id;

    private String description;

    private String details;

    private boolean done;

}

編輯啟動類別檔案以顯示下列內容。
```
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.ApplicationListener;
import org.springframework.context.annotation.Bean;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.stream.Collectors;
import java.util.stream.Stream;

@SpringBootApplication
public class DemoApplication {

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

    @Bean
    ApplicationListener<ApplicationReadyEvent> basicsApplicationListener(TodoRepository repository) {
        return event->repository
            .saveAll(Stream.of("A", "B", "C").map(name->new Todo("configuration", "congratulations, you have set up correctly!", true)).collect(Collectors.toList()))
            .forEach(System.out::println);
    }

}

interface TodoRepository extends JpaRepository<Todo, Long> {

}
```
提示

在本教學課程中，組態或程式代碼中沒有任何驗證作業。不過，連線到 Azure 服務需要驗證。若要完成驗證，您需要使用 Azure Identity。 Spring Cloud Azure 使用 DefaultAzureCredential，Azure 身分識別連結庫會提供它來協助您取得認證，而不需要變更任何程序代碼。

DefaultAzureCredential 支援多種驗證方法，並在執行階段判斷應使用的方法。這種方法可讓您的應用程式在不同的環境中使用不同的驗證方法（例如本機和生產環境），而不需要實作環境特定的程序代碼。如需詳細資訊，請參閱 DefaultAzureCredential。

若要在本機開發環境中完成驗證，您可以使用 Azure CLI、Visual Studio Code、PowerShell 或其他方法。如需詳細資訊，請參閱 Java 開發環境中的 Azure 驗證。若要在 Azure 裝載環境中完成驗證，建議您使用使用者指派的受控識別。如需詳細資訊，請參閱什麼是 Azure 資源受控識別？

啟動應用程式。您會看到類似下列範例的記錄：

2023-02-01 10:29:19.763 DEBUG 4392 --- [main] org.hibernate.SQL : insert into todo (description, details, done, id) values (?, ?, ?, ?)
com.example.demo.Todo@1f

部署至 Azure Spring Apps

現在您已在本機執行 Spring Boot 應用程式，現在可以將其移至生產環境。 Azure Spring Apps 可讓您輕鬆地將 Spring Boot 應用程式部署至 Azure，而不需要變更任何程式代碼。服務會管理 Spring 應用程式的基礎結構，讓開發人員可以專注於處理程式碼。 Azure Spring 應用程式提供生命週期管理，使用全方位的監視和診斷、組態管理、服務探索、持續整合與持續傳遞的整合、藍綠部署等等。若要將應用程式部署至 Azure Spring Apps，請參閱將第一個應用程式部署至 Azure Spring Apps。

下一步

適用於 Spring 開發人員的 Azure Spring Cloud Azure PostgreSQL 範例

共用方式為

搭配適用於 PostgreSQL 的 Azure 資料庫使用 Spring Data JPA

必要條件

請參閱範例應用程式

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

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

從適用於 PostgreSQL 的 Azure 資料庫儲存數據

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫

請參閱範例應用程式

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

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

從適用於 PostgreSQL 的 Azure 資料庫儲存數據

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫

部署至 Azure Spring Apps

下一步

意見反應

其他資源

共用方式為

搭配 適用於 PostgreSQL 的 Azure 資料庫 使用 Spring Data JPA

必要條件

請參閱範例應用程式

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

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

從 適用於 PostgreSQL 的 Azure 資料庫 儲存數據

將 Spring Boot 設定為使用 適用於 PostgreSQL 的 Azure 資料庫

請參閱範例應用程式

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

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

從 適用於 PostgreSQL 的 Azure 資料庫 儲存數據

將 Spring Boot 設定為使用 適用於 PostgreSQL 的 Azure 資料庫

部署至 Azure Spring Apps

下一步

意見反應

其他資源

搭配適用於 PostgreSQL 的 Azure 資料庫使用 Spring Data JPA

從適用於 PostgreSQL 的 Azure 資料庫儲存數據

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫

從適用於 PostgreSQL 的 Azure 資料庫儲存數據

將 Spring Boot 設定為使用適用於 PostgreSQL 的 Azure 資料庫