Connecting to Postgres from Spring Boot App in Heroku

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:

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.

As always, the code is available over on GitHub.