從 Heroku 上的 Spring Boot 應用程式連接到 Postgres

1. 概述

Heroku Postgres 為 Java 應用程式提供了多種連接到託管 PostgreSQL 實例的方式。在本教程中，我們將介紹一種與 Spring Boot 無縫整合的實用方法。具體來說，我們將探討如何使用 Heroku Postgres 提供的連接機制，並確保我們的應用程式即使在 Heroku 定期輪換存取憑證的情況下也能保持連接。

2. 設定

為了演示主要方法，我們使用一個簡單的 Spring Boot 應用程序，該應用程式將Book記錄持久化到關聯式資料庫中。首先，讓我們新增所需的依賴項：

<dependency>

 <groupId>org.springframework.boot</groupId>

 <artifactId>spring-boot-starter-data-jpa</artifactId>

 </dependency>

 <dependency>

 <groupId>org.springframework.boot</groupId>

 <artifactId>spring-boot-starter-validation</artifactId>

 </dependency>

 <dependency>

 <groupId>org.springframework.boot</groupId>

 <artifactId>spring-boot-starter-web</artifactId>

 </dependency>

 <dependency>

 <groupId>org.postgresql</groupId>

 <artifactId>postgresql</artifactId>

 <scope>runtime</scope>

 </dependency>

PostgreSQL 相依性提供了 JDBC 驅動程式。 JPA 啟動器捆綁了 Spring Data JPA 和 Hibernate，使我們能夠以最少的配置建立持久層。 驗證啟動器添加了對 Jakarta Bean Validation 的支援。

2.1 資料庫配置

接下來，我們設定application.yml文件，以定義應用程式如何與資料庫模式互動：

spring:

 jpa:

 hibernate:

 ddl-auto: validate

 properties:

 hibernate:

 dialect: org.hibernate.dialect.PostgreSQLDialect

將ddl-auto設定為validate會強制應用程式在啟動時將實體對應與資料庫架構進行比較。如果缺少必需的表或表不相容，應用程式將快速失敗。

然後我們定義兩個設定檔： local和heroku. local檔支援在本地運行的 PostgreSQL 實例上進行開發：

spring:

 config:

 activate:

 on-profile: local

 datasource:

 url: jdbc:postgresql://localhost:5432/demo

 username: demo

 password: demo

在heroku配置中，我們完全依賴 Heroku 注入的環境變數：

spring:

 config:

 activate:

 on-profile: heroku

 datasource:

 url: ${JDBC_DATABASE_URL:}

 username: ${JDBC_DATABASE_USERNAME:}

 password: ${JDBC_DATABASE_PASSWORD:}

由於 Heroku 會定期輪換資料庫憑證，因此將這些值硬編碼是不切實際的。

2.2. 便利性變數

啟動時，Heroku Spring 感知建構套件會設定SPRING_DATASOURCE_URL 、 SPRING_DATASOURCE_USERNAME和SPRING_DATASOURCE_PASSWORD環境變數。這些值與其 JDBC 等效值相對應，如下表所示：

JDBC_*	春天_*
JDBC_DATABASE_URL	SPRING_DATASOURCE_URL
JDBC_DATABASE_USERNAME	SPRING_DATASOURCE_USERNAME
JDBC_DATABASE_PASSWORD	SPRING_DATASOURCE_PASSWORD

我們可以根據配置的建置包交替使用這些工具。

2.3. 配置 Heroku Postgres

我們可以透過 Heroku 控制面板或 Heroku CLI 來配置 Heroku Postgres。在本例中，我們使用 CLI。

首先，我們進行身份驗證：

heroku login

接下來，我們建立一個 Heroku 應用程式：

heroku apps:create bookshelf-demo-app

此命令建立一個空應用程序，將其與 Git 儲存庫關聯，並為其分配一個公共 URL。

然後我們配置資料庫插件：

heroku addons:create heroku-postgresql --app bookshelf-demo-app

Heroku 會非同步配置資料庫，並在配置完成後重新啟動應用程序，如下面的輸出所示：

Creating heroku-postgresql on ⬢ bookshelf-demo-app... ~$0.007/hour (max $5/month)

 Database should be available soon

 postgresql-octagonal-60215 is being created in the background. The app will restart when

 complete...

請注意， Heroku 不再提供免費資料庫層級，因此配置資料庫可能會產生費用，具體取決於所選套餐。

3. 連接到 Heroku Postgres

資料庫配置完成後，我們可以探索不同的連線方案。由於應用程式會在啟動時驗證資料庫模式，因此所需的表必須在部署前存在。

我們先來檢查一下最近建立的資料庫：

heroku pg:info -a bookshelf-demo-app

輸出結果包括資料庫 URL、PostgreSQL 版本和產生的add-on名稱：

=== DATABASE_URL



 Plan: essential-0

 Status: Available

 Connections: 0/20

 PG Version: 17.6

 Created: 2026-01-23 10:32

 Data Size: 7.65 MB / 1 GB (0.75%) (In compliance)

 Tables: 0/4000 (In compliance)

 Fork/Follow: Unsupported

 Rollback: Unsupported

 Continuous Protection: Off

 Add-on: <heroku-generated-add-on-name>

我們使用add-on名稱來初始化架構。接下來，讓我們定義一個setup.sql檔：

CREATE TABLE books (

 id BIGSERIAL PRIMARY KEY,

 title VARCHAR(255) NOT NULL,

 author VARCHAR(255) NOT NULL

 );

最後，我們使用以下命令應用該模式：

heroku pg:psql <heroku-generated-add-on-name> -a bookshelf-demo-app < setup.sql

這個指令會針對我們託管的 Postgres 執行個體執行我們的setup.sql腳本。

3.1. 從 Heroku 應用程式連接

讓我們將 Spring Boot 應用程式部署到 Heroku：

git add .

 git commit -m "<commit message>"

 heroku git:remote -a bookshelf-demo-app

 git push heroku main

部署完成後，讓我們透過查看日誌來驗證啟動情況：

heroku logs --tail -a bookshelf-demo-app

成功的啟動過程包括狀態轉換到up 。現在我們可以透過 REST API 建立記錄：

curl -X POST https://bookshelf-demo-app-<heroku-generated-id>.herokuapp.com/api/books \

 -H "Content-Type: application/json" \

 -d '{"title":"Build your API with Spring","author":"Baeldung"}'

查詢資料庫確認書籍表中存在新行。

3.2. 從本機連接

在某些情況下，我們可能需要本地運行的應用程式直接連接到託管的 Heroku 資料庫以進行偵錯或檢查。由於 Heroku 會輪換憑證，我們首先使用 Heroku CLI 讀取產生的環境變數：

heroku run --app bookshelf-demo-app 'echo $JDBC_DATABASE_URL'

該命令會產生類似以下內容的輸出，其中包括使用者名稱和密碼：

Running echo $JDBC_DATABASE_URL on ⬢ bookshelf-demo-app... up, run.6575

 jdbc:postgresql://<cluster-name>:5432/<database-name>?password=<password>&sslmode=require&user=<username>

我們可以使用以下命令明確地檢索使用者名稱和密碼：

heroku run --app bookshelf-demo-app 'echo $JDBC_DATABASE_USERNAME'

 heroku run --app bookshelf-demo-app 'echo $JDBC_DATABASE_PASSWORD'

接下來，我們將解析後的值儲存在本地的.env檔案中：

DATASOURCE_URL="<heroku-jdbc-database-url>"

 DATASOURCE_USERNAME="<heroku-jdbc-database-username>"

 DATASOURCE_PASSWORD="<heroku-jdbc-database-password>"

之後，我們在application.yml中引用這些值：

spring:

 config:

 activate:

 on-profile: local

 datasource:

 url: ${DATASOURCE_URL}

 username: ${DATASOURCE_USERNAME}

 password: ${DATASOURCE_PASSWORD}

在我們的開發環境中，我們可以在本地運行應用程式時直接傳遞.env檔：

export $(cat .env | xargs) && mvn spring-boot:run -Dspring-boot.run.profiles=local

這種設定允許本地 Spring Boot 實例安全地連接到同一個資料庫，而無需將敏感憑證嵌入到原始碼控制中。

4. 結論

在本教程中，我們示範如何使用環境驅動配置將 Spring Boot 應用程式連接到 Heroku Postgres 資料庫。我們配置了託管資料庫，初始化了資料庫模式，部署了應用程序，並從 Heroku 和本地開發環境進行了連接。透過將 Spring Profiles 與環境變數結合，我們實現了安全、可移植且符合 Heroku 運維模式的配置。

和往常一樣，程式碼可以在 GitHub 上找到。