Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

Heroku Postgres offers several ways for Java applications to connect to a managed PostgreSQL instance. In this tutorial, we walk through a practical approach that integrates seamlessly with Spring Boot. Specifically, we look at how to use the Heroku Postgres-provided connection mechanism and ensure our application remains connected despite Heroku’s periodic rotation of access credentials.

2. Setup

To demonstrate the primary approach, we use a simple Spring Boot application that persists Book records in a relational database. Let’s start by adding the required dependencies:

<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>

The PostgreSQL dependency provides the JDBC driver. The JPA starter bundles Spring Data JPA and Hibernate, allowing us to build a persistence layer with minimal configuration. The validation starter adds support for Jakarta Bean Validation.

2.1. Database Configuration

Next, we configure our application.yml to define how the application interacts with the database schema:

spring:
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect

Setting ddl-auto to validate forces the application to compare entity mappings against the database schema at startup. If required tables are missing or incompatible, the application fails fast.

We then define two profiles, local and heroku. The local profile supports development against a locally running PostgreSQL instance:

spring:
  config:
    activate:
      on-profile: local
  datasource:
    url: jdbc:postgresql://localhost:5432/demo
    username: demo
    password: demo

In the heroku profile, we rely entirely on environment variables injected by Heroku:

spring:
  config:
    activate:
      on-profile: heroku
  datasource:
    url: ${JDBC_DATABASE_URL:}
    username: ${JDBC_DATABASE_USERNAME:}
    password: ${JDBC_DATABASE_PASSWORD:}

Since Heroku regularly rotates database credentials, hardcoding these values isn’t practical.

2.2. Convenience Variables

At startup, the Heroku Spring-aware buildpacks set the SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, and SPRING_DATASOURCE_PASSWORD environment variables. These values mirror their JDBC equivalents, as shown in the table below:

JDBC_* SPRING_*
JDBC_DATABASE_URL SPRING_DATASOURCE_URL
JDBC_DATABASE_USERNAME SPRING_DATASOURCE_USERNAME
JDBC_DATABASE_PASSWORD SPRING_DATASOURCE_PASSWORD

We can use these interchangeably based on the configured buildpacks.

2.3. Provisioning Heroku Postgres

We can provision Heroku Postgres through either the dashboard or the Heroku CLI. In this example, we use the CLI.

First, we authenticate:

heroku login

Next, we create a Heroku application:

heroku apps:create bookshelf-demo-app

This command creates an empty application, associates it with a Git repository, and assigns it a public URL.

We then provision the database add-on:

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

Heroku provisions the database asynchronously and restarts the application once the process completes, as shown in the output below:

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...

Note that Heroku no longer offers a free database tier, so provisioning a database may incur costs depending on the selected plan.

3. Connecting to Heroku Postgres

With the database provisioned, we can explore different connection scenarios. Because the application validates the schema at startup, the required tables must exist before deployment.

Let’s start by inspecting the recently provisioned database:

heroku pg:info -a bookshelf-demo-app

The output includes the database URL, PostgreSQL version, and the generated add-on name:

=== 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>

We use the add-on name to initialize the schema. Next, let’s define a setup.sql file:

CREATE TABLE books (
    id BIGSERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    author VARCHAR(255) NOT NULL
);

Lastly, we apply the schema using the following command:

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

The command executes our setup.sql script against our hosted Postgres instance.

3.1. Connecting from the Heroku Application

Let’s deploy our Spring Boot application to Heroku:

git add .
git commit -m "<commit message>"
heroku git:remote -a bookshelf-demo-app
git push heroku main

After deployment, let’s verify startup by checking the logs:

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

A successful startup includes a state transition to up. We can now create a record through the 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"}'

Querying the database confirms that the new row exists in the books table.

3.2. Connecting from Localhost

In some cases, we may want a locally running application to connect directly to the hosted Heroku database for debugging or inspection. Since Heroku rotates credentials, let’s start by reading the generated environment variables using Heroku CLI:

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

The command produces output similar to the following, which includes a username and password:

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>

We can explicitly retrieve the username and password using the command below:

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

Next, we store the resolved values in a local .env file:

DATASOURCE_URL="<heroku-jdbc-database-url>"
DATASOURCE_USERNAME="<heroku-jdbc-database-username>"
DATASOURCE_PASSWORD="<heroku-jdbc-database-password>"

We thereafter reference these values from our application.yml:

spring:
  config:
    activate:
      on-profile: local
  datasource:
    url: ${DATASOURCE_URL}
    username: ${DATASOURCE_USERNAME}
    password: ${DATASOURCE_PASSWORD}

In our development environment, we can then simply pass the .env file when running the application locally:

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

This setup allows a local Spring Boot instance to connect securely to the same database without embedding sensitive credentials in source control.

4. Conclusion

In this tutorial, we demonstrated how a Spring Boot application connects to Heroku Postgres using environment-driven configuration. We provisioned a managed database, initialized the schema, deployed the application, and connected from both Heroku and a local development environment. By combining Spring profiles with environment variables, we achieved a configuration that is secure, portable, and aligned with Heroku’s operational model.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW