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

發行項
11/25/2024

本文示範如何建立使用 Spring Data R2DBC 在適用於 PostgreSQL 的 Azure 資料庫資料庫中儲存和擷取資訊的範例應用程式。此範例會從 GitHub 上的 r2dbc-postgresql 存放庫使用適用於 PostgreSQL 的 R2DBC 實作。

R2DBC 會將反應式 API 帶入傳統關係資料庫。您可以將它與 Spring WebFlux 搭配使用，以建立使用非封鎖 API 的完整回應式 Spring Boot 應用程式。其可提供比傳統「每個連線一個線程」方法更好的延展性。

必要條件

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

PostgreSQL 命令行用戶端。
cURL 或類似的 HTTP 公用程式來測試功能。

請參閱範例應用程式

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

準備工作環境

首先，執行下列命令來設定一些環境變數：

export AZ_RESOURCE_GROUP=database-workshop
export AZ_DATABASE_SERVER_NAME=<YOUR_DATABASE_SERVER_NAME>
export AZ_DATABASE_NAME=<YOUR_DATABASE_NAME>
export AZ_LOCATION=<YOUR_AZURE_REGION>
export AZ_POSTGRESQL_ADMIN_USERNAME=spring
export AZ_POSTGRESQL_ADMIN_PASSWORD=<YOUR_POSTGRESQL_ADMIN_PASSWORD>
export AZ_POSTGRESQL_NON_ADMIN_USERNAME=nonspring
export AZ_POSTGRESQL_NON_ADMIN_PASSWORD=<YOUR_POSTGRESQL_NON_ADMIN_PASSWORD>
export AZ_LOCAL_IP_ADDRESS=<YOUR_LOCAL_IP_ADDRESS>

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

<YOUR_DATABASE_SERVER_NAME>：您的 PostgreSQL 伺服器名稱，這在整個 Azure 中應該是唯一的。
<YOUR_DATABASE_NAME>:P ostgreSQL 伺服器的資料庫名稱，在 Azure 中應該是唯一的。
<YOUR_AZURE_REGION>：您將使用的 Azure 區域。根據預設，您可以使用 eastus，但建議您將區域設定為您居住地附近的位置。您可以使用檢視可用區域 az account list-locations的完整清單。
<YOUR_POSTGRESQL_ADMIN_PASSWORD> 和 <YOUR_POSTGRESQL_NON_ADMIN_PASSWORD>:P ostgreSQL 資料庫伺服器的密碼，其至少應有八個字元。這些字元應屬於下列三種類別：英文大寫字母、英文小寫字母、數字 (0-9) 及非英數字元 (!、$、#、% 等等)。
<YOUR_LOCAL_IP_ADDRESS>：本機電腦的 IP 位址，您將在此電腦執行 Spring Boot 應用程式。您可以開啟 whatismyip.akamai.com，以便找出此資訊。

注意

Microsoft 建議您使用最安全的可用驗證流程。此程式中所述的驗證流程，例如資料庫、快取、傳訊或 AI 服務，在應用程式中需要高度的信任，而且不會在其他流程中帶來風險。只有在更安全的選項，例如無密碼或無密鑰連線的受控識別時，才能使用此流程。針對本機計算機作業，偏好使用無密碼或無密鑰連線的使用者身分識別。

接下來，使用下列命令建立資源群組：

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

建立適用於 PostgreSQL 的 Azure 資料庫實例並設定系統管理員使用者

您首先要建立的是具有系統管理員使用者的受控 PostgreSQL 伺服器。

注意

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

az postgres flexible-server create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --location $AZ_LOCATION \
    --admin-user $AZ_POSTGRESQL_ADMIN_USERNAME \
    --admin-password $AZ_POSTGRESQL_ADMIN_PASSWORD \
    --yes \
    --output tsv

設定 PostgreSQL 資料庫

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

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

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

適用於 PostgreSQL 的 Azure 資料庫執行個體依預設會受到保護。其防火牆不允許任何連入連線。若要能夠使用您的資料庫，您必須新增防火牆規則，讓本機 IP 位址能夠存取資料庫伺服器。

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

az postgres flexible-server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_SERVER_NAME \
    --rule-name $AZ_DATABASE_SERVER_NAME-database-allow-local-ip \
    --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 位址的環境變數：

export AZ_WSL_IP_ADDRESS=<the-copied-IP-address>

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

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

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

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

注意

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

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

注意

cat << EOF > create_user.sql
CREATE ROLE "$AZ_POSTGRESQL_NON_ADMIN_USERNAME" WITH LOGIN PASSWORD '$AZ_POSTGRESQL_NON_ADMIN_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE $AZ_DATABASE_NAME TO "$AZ_POSTGRESQL_NON_ADMIN_USERNAME";
EOF

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

psql "host=$AZ_DATABASE_SERVER_NAME.postgres.database.azure.com user=$AZ_POSTGRESQL_ADMIN_USERNAME dbname=$AZ_DATABASE_NAME port=5432 password=$AZ_POSTGRESQL_ADMIN_PASSWORD sslmode=require" < create_user.sql

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

rm create_user.sql

建立回應式 Spring Boot 應用程式

若要建立回應式 Spring Boot 應用程式，我們將使用 Spring Initializr。我們將建立的應用程式會使用：

Spring Boot 2.7.11。
下列相依性：Spring Reactive Web（也稱為 Spring WebFlux）和 Spring Data R2DBC。

使用 Spring Initializr 產生應用程式

使用下列命令在命令列上產生應用程式：

curl https://start.spring.io/starter.tgz -d dependencies=webflux,data-r2dbc -d baseDir=azure-database-workshop -d bootVersion=2.7.11 -d javaVersion=17 | tar -xzvf -

新增回應式 PostgreSQL 驅動程序實作

開啟產生的專案 pom.xml 檔案，然後從 GitHub 上的 r2dbc-postgresql 存放庫新增回應式 PostgreSQL 驅動程式。相 spring-boot-starter-webflux 依性之後，新增下列文字：

<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
    <version>0.8.12.RELEASE</version>
    <scope>runtime</scope>
</dependency>

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

開啟 src/main/resources/application.properties 檔案，然後新增下列文字：

logging.level.org.springframework.data.r2dbc=DEBUG

spring.r2dbc.url=r2dbc:pool:postgres://$AZ_DATABASE_SERVER_NAME.postgres.database.azure.com:5432/$AZ_DATABASE_NAME
spring.r2dbc.username=nonspring
spring.r2dbc.password=$AZ_POSTGRESQL_NON_ADMIN_PASSWORD
spring.r2dbc.properties.sslMode=REQUIRE

將 $AZ_DATABASE_SERVER_NAME、 $AZ_DATABASE_NAME和 $AZ_POSTGRESQL_NON_ADMIN_PASSWORD 變數取代為您在本文中開頭所設定的值。

警告

基於安全性考慮，適用於 PostgreSQL 的 Azure 資料庫需要使用 SSL 連線。這就是為什麼您需要新增組 spring.r2dbc.properties.sslMode=REQUIRE 態屬性，否則 R2DBC PostgreSQL 驅動程式會嘗試使用不安全的連線進行連線，這將會失敗。

注意

為了提升效能， spring.r2dbc.url 屬性會設定為使用 r2dbc-pool 使用連線集區。

您現在應該可以使用提供的 Maven 包裝函式來啟動應用程式，如下所示：

./mvnw spring-boot:run

以下是第一次執行的應用程式螢幕快照：

建立資料庫結構描述

在 main DemoApplication 類別內，使用下列程式代碼，設定將建立資料庫架構的新 Spring bean：

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.core.io.ClassPathResource;
import org.springframework.data.r2dbc.connectionfactory.init.ConnectionFactoryInitializer;
import org.springframework.data.r2dbc.connectionfactory.init.ResourceDatabasePopulator;

import io.r2dbc.spi.ConnectionFactory;

@SpringBootApplication
public class DemoApplication {

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

    @Bean
    public ConnectionFactoryInitializer initializer(ConnectionFactory connectionFactory) {
        ConnectionFactoryInitializer initializer = new ConnectionFactoryInitializer();
        initializer.setConnectionFactory(connectionFactory);
        ResourceDatabasePopulator populator = new ResourceDatabasePopulator(new ClassPathResource("schema.sql"));
        initializer.setDatabasePopulator(populator);
        return initializer;
    }
}

這個 Spring bean 使用稱為 schema.sql 的 檔案，因此請在 src/main/resources 資料夾中建立該檔案，然後新增下列文字：

DROP TABLE IF EXISTS todo;
CREATE TABLE todo (id SERIAL PRIMARY KEY, description VARCHAR(255), details VARCHAR(4096), done BOOLEAN);

停止執行中的應用程式，然後使用下列命令再次啟動它。應用程式現在會使用 demo 您稍早建立的資料庫，並在其中建立 todo 數據表。

./mvnw spring-boot:run

以下是建立資料庫資料表的螢幕快照：

編碼應用程式

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

使用下列程式代碼，在類別旁邊DemoApplication建立新的 Todo Java 類別：

package com.example.demo;

import org.springframework.data.annotation.Id;

public class Todo {

    public Todo() {
    }

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

    @Id
    private Long id;

    private String description;

    private String details;

    private boolean 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;
    }
}

這個類別是在您先前建立的 todo 資料表上對應的領域模型。

需要有存放庫才能管理該類別。使用下列程式代碼，在相同的套件中定義新的 TodoRepository 介面：

package com.example.demo;

import org.springframework.data.repository.reactive.ReactiveCrudRepository;

public interface TodoRepository extends ReactiveCrudRepository<Todo, Long> {
}

此存放庫是 Spring Data R2DBC 管理的回應式存放庫。

建立可儲存和擷取資料的控制器以完成應用程式。在相同的套件中實作 TodoController 類別，並新增下列程式碼：

package com.example.demo;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@RestController
@RequestMapping("/")
public class TodoController {

    private final TodoRepository todoRepository;

    public TodoController(TodoRepository todoRepository) {
        this.todoRepository = todoRepository;
    }

    @PostMapping("/")
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<Todo> createTodo(@RequestBody Todo todo) {
        return todoRepository.save(todo);
    }

    @GetMapping("/")
    public Flux<Todo> getTodos() {
        return todoRepository.findAll();
    }
}

最後，停止應用程式，然後使用下列命令再次啟動它：

./mvnw spring-boot:run

測試應用程式

若要測試應用程式，您可以使用 cURL。

首先，使用下列命令在資料庫中建立新的「todo」專案：

curl --header "Content-Type: application/json" \
    --request POST \
    --data '{"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done": "true"}' \
    http://127.0.0.1:8080

此命令應該會傳回已建立的專案，如下所示：

{"id":1,"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done":true}

接下來，使用新的 cURL 要求搭配下列命令來擷取數據：

curl http://127.0.0.1:8080

此命令會傳回「todo」項目清單，包括您所建立的專案，如下所示：

[{"id":1,"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done":true}]

以下是這些 cURL 要求的螢幕快照：

恭喜！您已建立使用 R2DBC 從適用於 PostgreSQL 的 Azure 資料庫儲存和擷取數據的完全反應式 Spring Boot 應用程式。

清除資源

若要清除本快速入門期間使用的所有資源，請使用下列命令刪除資源群組：

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

下一步

若要深入瞭解如何將 Spring Data 應用程式部署至 Azure Spring Apps 和使用受控識別，請參閱教學課程：使用無密碼連線將 Spring 應用程式部署至 Azure Spring Apps。

若要深入了解 Spring 和 Azure，請繼續閱讀「Azure 上的 Spring」文件中心中的資訊。

Azure 上的 Spring

另請參閱

如需 Spring Data R2DBC 的詳細資訊，請參閱 Spring 的參考檔。

如需如何搭配使用 Azure 和 Java 的詳細資訊，請參閱適用於 Java 開發人員的 Azure 和使用 Azure DevOps 和 Java。

共用方式為

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

必要條件

請參閱範例應用程式

準備工作環境

建立適用於 PostgreSQL 的 Azure 資料庫實例並設定系統管理員使用者

設定 PostgreSQL 資料庫

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

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

建立回應式 Spring Boot 應用程式

使用 Spring Initializr 產生應用程式

新增回應式 PostgreSQL 驅動程序實作

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

建立資料庫結構描述

編碼應用程式

測試應用程式

清除資源

下一步

另請參閱

意見反應

其他資源

共用方式為

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

必要條件

請參閱範例應用程式

準備工作環境

建立 適用於 PostgreSQL 的 Azure 資料庫 實例並設定系統管理員使用者

設定 PostgreSQL 資料庫

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

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

建立回應式 Spring Boot 應用程式

使用 Spring Initializr 產生應用程式

新增回應式 PostgreSQL 驅動程序實作

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

建立資料庫結構描述

編碼應用程式

測試應用程式

清除資源

下一步

另請參閱

意見反應

其他資源

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

建立適用於 PostgreSQL 的 Azure 資料庫實例並設定系統管理員使用者

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