搭配使用 Spring Data R2DBC 搭配 適用於 PostgreSQL 的 Azure 資料庫
本文示範如何建立使用 Spring Data R2DBC 在 適用於 PostgreSQL 的 Azure 資料庫 資料庫中儲存和擷取資訊的範例應用程式。 此範例會從 GitHub 上的 r2dbc-postgresql 存放庫使用適用於 PostgreSQL 的 R2DBC 實作。
R2DBC 會將反應式 API 帶入傳統關係資料庫。 您可以將它與 Spring WebFlux 搭配使用,以建立使用非封鎖 API 的完整回應式 Spring Boot 應用程式。 其可提供比傳統「每個連線一個線程」方法更好的延展性。
必要條件
Azure 訂用帳戶 - 免費建立一個訂用帳戶。
Java Development Kit (JDK)版本 8 或更高版本。
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>
:P ostgreSQL 伺服器的名稱,在 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。
接下來,使用下列命令建立資源群組:
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 的 Azure 資料庫 中建立使用者中,閱讀有關建立 PostgreSQL 用戶的詳細資訊。
建立名為 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 檔中心。
另請參閱
如需 Spring Data R2DBC 的詳細資訊,請參閱 Spring 的 參考檔。
如需如何搭配使用 Azure 和 Java 的詳細資訊,請參閱適用於 Java 開發人員的 Azure 和使用 Azure DevOps 和 Java。