Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Working with Django
      • Background Jobs in Python
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Java Advanced Topics
      • Working with Spring Boot
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Add-ons
  • All Add-ons
  • Borealis Isolated Postgres
Borealis Isolated Postgres

This add-on is operated by Borealis Data Solutions

A PostgreSQL database add-on that takes security seriously.

Borealis Isolated Postgres

Last updated June 06, 2022

The Borealis Isolated Postgres add-on is currently in beta.

Table of Contents

  • Getting Started
  • Connecting to the Database
  • Encryption
  • Accessing the Dashboard
  • Troubleshooting
  • Data Storage Limits
  • Migrating Between Plans
  • Removing the Add-on
  • Support
  • Attribution

The Borealis Isolated Postgres add-on provides PostgreSQL-compatible database clusters as a service on Amazon RDS. PostgreSQL is a powerful open-source relational database that is well suited to a variety of transactional workloads. Amazon RDS provides a highly optimized and reliable platform for managed database clusters.

Borealis Isolated Postgres isolates each database cluster from the public internet; a client can only connect to a database via a secure tunnel using strong authentication and encryption. Configuring an app to connect via a secure tunnel is transparent to application code.

All PostgreSQL-compatible client libraries work with Borealis Isolated Postgres for the languages supported by Heroku (Ruby, Python, Java, Node.js, Go, PHP, Clojure, and Scala).

Getting Started

Installing the Add-on

You can attach the Borealis Isolated Postgres add-on to an app using the CLI:

See a list of all available plans here.

$ heroku addons:create borealis-pg
Creating borealis-pg on ⬢ example-app... free
borealis-pg-example-addon is being created in the background. The app will restart when complete...

Provisioning of a Borealis Isolated Postgres add-on is asynchronous and can take several minutes. To wait for an add-on to finish provisioning via the CLI:

$ heroku addons:wait
Creating borealis-pg-example-addon... done

After you provision Borealis Isolated Postgres, two config vars are available in your app’s settings: DATABASE_URL and DATABASE_SSH_TUNNEL_BPG_CONNECTION_INFO. If your app already has a Heroku Postgres database and you provision a Borealis Isolated Postgres instance, the config var name has the format BOREALIS_PG_<COLOR>_URL and BOREALIS_PG_<COLOR>_SSH_TUNNEL_BPG_CONNECTION_INFO (for example, BOREALIS_PG_RED_URL and BOREALIS_PG_RED_SSH_TUNNEL_BPG_CONNECTION_INFO). Use the appropriate config var in your app.

You can confirm the config var contains the canonical URL used for read and write connections to the database cluster with the heroku config:get command:

$ heroku config:get DATABASE_URL
postgres://user:pass@host:port/dbname

The DATABASE_SSH_TUNNEL_BPG_CONNECTION_INFO contains the connection information required to establish a secure tunnel. It’s used by the companion buildpack (borealis/postgres-ssh). You don’t need it in your application code.

Installing the Buildpack

Apps require the companion buildpack (borealis/postgres-ssh) to connect to an add-on database. After installation, the buildpack automatically uses the connection information in the add-on’s config vars to establish a secure tunnel to the corresponding database cluster. Any client process that connects using the DATABASE_URL config var automatically sends its database traffic through the secure tunnel.

The following sections describe how to apply the buildpack using either a slug (the standard option) or a Docker container (via Cloud Native Buildpacks or a Dockerfile).

Standard Deploy (Slug)

If you’re using a standard deployment, you can add the buildpack using the following CLI command:

$ heroku buildpacks:add --index 1 borealis/postgres-ssh

After adding a buildpack to a slug app, you must deploy a new version of the app (for example, by pushing with git) for the buildpack to take effect.

Cloud Native Buildpack Deploy (Docker)

You can build an image using Cloud Native Buildpacks. To build an image, you must install Pack, a tool that supports the use of Cloud Native Buildpacks.

The following example shows how to build an image with the borealis/postgres-ssh, heroku/ruby, and heroku/procfile buildpacks. These buildpacks include support for the Borealis Isolated Postgres add-on, the Ruby language, and a Procfile, respectively:

$ pack build --buildpack https://buildpack-registry.heroku.com/cnb/borealis/postgres-ssh --buildpack heroku/ruby --buildpack heroku/procfile --builder heroku/buildpacks example-app

The heroku/procfile buildpack is necessary if your app has a Procfile. Don’t include it otherwise.

There’s a Cloud Native Buildpack for every supported language. You can include a language’s Cloud Native Buildpack using the same name as its standard buildpack in a pack build command. For a list of buildpacks for supported languages, see Buildpacks.

To include other standard buildpacks as Cloud Native Buildpacks, you can use the Cloud Native Buildpacks shim. Simply append the buildpack’s name to the end of the URL https://buildpack-registry.heroku.com/cnb/ (for example, to include jincod/dotnetcore-buildpack, use https://buildpack-registry.heroku.com/cnb/jincod/dotnetcore-buildpack in the pack build command).

Next, tag and push the image to Heroku’s Docker registry:

$ docker tag example-app registry.heroku.com/example-app/web
$ docker push registry.heroku.com/example-app/web

Finally, release the app on Heroku:

$ heroku container:release --app example-app web

For more information about deploying and running Docker containers, see Container Registry & Runtime (Docker Deploys).

Dockerfile Deploy (Docker)

You can define your app’s Docker image manually in a Dockerfile. The following Dockerfile for Heroku’s python-getting-started app shows how to set up a secure tunnel:

FROM python:3.10

# Download, build, and move the autossh executable to the location expected by
# the buildpack's secure tunnel startup script (the /usr/bin directory)
WORKDIR /tmp
RUN wget https://www.harding.motd.ca/autossh/autossh-1.4g.tgz && \
  tar -x --file autossh-1.4g.tgz && \
  cd autossh-1.4g && \
  ./configure && \
  make && \
  mv autossh /usr/bin && \
  cd .. && \
  rm -rf autossh-1.4g autossh-1.4g.tgz

# Copy the app's files and install its dependencies
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

# Download the secure tunnel startup script from the borealis/postgres-ssh
# buildpack
RUN wget https://raw.githubusercontent.com/OldSneerJaw/heroku-buildpack-borealis-pg-ssh/main/profile.d/borealis-pg-init-ssh-tunnel.sh && \
  chmod u+x borealis-pg-init-ssh-tunnel.sh

# Set the command that establishes the SSH tunnel and launches the app when
# the container starts
CMD ./borealis-pg-init-ssh-tunnel.sh && gunicorn gettingstarted.wsgi

Follow the Container Registry & Runtime (Docker Deploys) documentation to build the image and deploy to Heroku using the heroku container:push and heroku container:release commands.

A heroku.yml file is a convenient way to manage building, deploying, and running a Dockerfile-based app on Heroku.

Connecting to the Database

Connecting with Ruby

Use the pg gem to connect to a PostgreSQL database in Ruby. Add it to the project’s Gemfile, then install all dependencies using bundler:

$ bundle install

Pass the DATABASE_URL config var directly to the PG.connect method to connect to the database:

require 'pg'

db_conn = PG.connect(connection_string: ENV["DATABASE_URL"])

Modern versions of the Rails framework have built-in support for the DATABASE_URL config var, so you don’t need to configure it to use it with Active Record.

For more information about using this gem, see pg.

Connecting with Python

Use the psycopg package to connect to a PostgreSQL database in Python. Add it to the project’s requirements.txt, then install all dependencies using pip:

$ pip install -r requirements.txt

Pass the DATABASE_URL config var directly to psycopg’s connect function:

import os
import psycopg

db_conn = psycopg.connect(os.environ["DATABASE_URL"])

If you’re using Django, install the dj-database-url package. Configure the database used by Django’s ORM from the DATABASE_URL config var.

For more information, see psycopg.

Connecting with Java

Use the PostgreSQL JDBC driver to connect to a PostgreSQL database in Java. The official Java buildpack automatically creates JDBC_DATABASE_URL and SPRING_DATASOURCE_URL environment variables when it detects a DATABASE_URL config var. These environment variables are suitable for many common situations. The JDBC connection info can be parsed directly from the DATABASE_URL config var when they aren’t supported.

For example, pass the JDBC_DATABASE_URL environment variable directly to the DriverManager‘s getConnection method:

var dbConn = DriverManager.getConnection(System.getenv("JDBC_DATABASE_URL"));

Connecting with Node.js

Use the pg package to connect to a PostgreSQL database in Node.js. Add it to the project’s package.json and install it in one command:

$ npm install --save pg

Pass the DATABASE_URL config var to the Client constructor:

const {Client} = require('pg');

const dbClient = new Client({connectionString: process.env.DATABASE_URL});
await dbClient.connect();

For more information, see node-postgres.

Connecting with Go

Use the pq database driver to connect to a PostgreSQL database in Go. Add it to the project’s go.mod and install it in one command:

$ go get github.com/lib/pq

Pass the DATABASE_URL config var to the sql.Open method:

import (
    "database/sql"

    _ "github.com/lib/pq"
)

func main() {
    dbConn, dbErr := sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if dbErr != nil {
        log.Fatalf("Error connecting to database: %q", dbErr)
    }
}

For more information, see Go pq.

Connecting with PHP

Use the pgsql extension to connect to a PostgreSQL database in PHP:

$db_conn = pg_connect(getenv("DATABASE_URL"));

You can also use PHP Data Objects (PDO) for a slightly higher-level abstraction, which requires the use of the parse_url function to retrieve connection info:

$dbinfo = parse_url(getenv("DATABASE_URL"));
$dbname = ltrim($dbinfo["path"], "/")
$dbconn = new PDO("pgsql:host=" . $dbinfo["host"] . ";port=" . $dbinfo["port"] . ";dbname=" . $dbname . ";user=" . $dbinfo["user"] . ";password=" . $dbinfo["pass"]);

Local Connections

You can connect to a Borealis Isolated Postgres add-on database cluster locally on the command line by using the borealis-pg-cli plugin for the Heroku CLI.

Install the plugin:

$ heroku plugins:install borealis-pg-cli

Next, open a secure tunnel and submit SQL queries to the database using a tool like psql or pgAdmin:

$ heroku borealis-pg:tunnel --addon DATABASE

You can use the borealis-pg-cli plug-in to add and remove PostgreSQL extensions, start sessions, and execute database migration scripts through a secure tunnel to a database cluster. For more information about borealis-pg-cli commands, see borealis-pg-cli.

Encryption

All connections to a Borealis Isolated Postgres database cluster use a secure tunnel. Data is automatically encrypted in transit. All data stored in the database cluster is encrypted when at rest. For an added layer of transport security, ensure that your app connects with the sslmode connection parameter set to require.

Accessing the Dashboard

To access the add-on dashboard, open the Heroku Dashboard, choose an application, and then select Borealis Isolated Postgres from the Add-ons menu.

For more information on the features available within the Borealis Isolated Postgres dashboard, see Borealis Isolated Postgres Add-on Management.

Troubleshooting

A missing borealis/postgres-ssh buildpack causes most connection issues. The buildpack is required in order to establish a secure tunnel between your app and the database server. Without the buildpack installed you are likely to encounter an error similar to the following:

connection to server at "pg-tunnel.borealis-data.com" (127.0.0.1), port 65535 failed: Connection refused
Is the server running on that host and accepting TCP/IP connections?

You can verify your buildpack using the following CLI command:

$ heroku buildpacks
=== example-app Buildpack URLs
1. borealis/postgres-ssh
2. heroku/java

If it’s missing, see Installing the Buildpack for more information about how to add it to the app.

If the buildpack isn’t missing, verify that you’ve deployed a new version of the app. Pushing a code change forces Heroku to use the new buildpack. If problems persist, make sure you’ve configured the app to use the correct language-specific PostgreSQL connection URL config var.

Finally, verify that you’re using the correct Borealis Isolated Postgres add-on attachment name. Check the name in your config vars and remember that you can rename attachments with heroku addons:rename.

Data Storage Limits

Each add-on plan has a database storage limit. As an add-on’s database size approaches the storage limit for the plan, you will be sent a courtesy notice at the email address associated with your Heroku user account. Any add-on database that persistently exceeds its storage limit will eventually be made read-only (although rest assured that no pre-existing data will be lost in such cases) until it is upgraded to a plan with enough storage available.

Migrating Between Plans

Application owners must carefully manage the migration timing to ensure proper application function during the migration process.

When switching to a different database node size, the migration process can take several minutes. After the migration, your app can experience a brief period of downtime (typically less than a minute) as the database cluster switches over to the new database node(s). Otherwise, there’s no down time for your app.

The plan migration is asynchronous. The app config vars for the add-on update after the migration completes.

Use the heroku addons:upgrade command to migrate to a new plan:

$ heroku addons:upgrade borealis-pg:newplan
Upgrading borealis-pg-example-addon to borealis-pg:newplan on ⬢ example-app... done
Your plan has been updated to: borealis-pg:newplan

Removing the Add-on

You can remove Borealis Isolated Postgres via the CLI:

This action destroys all associated data and can’t be undone!

$ heroku addons:destroy borealis-pg
Destroying borealis-pg-example-addon on ⬢ example-app... done

Before removing Borealis Isolated Postgres, you can export your data using any standard PostgreSQL data export tool (for example, pg_dump).

Support

Submit all Borealis Isolated Postgres support and runtime issues using one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@borealis-data.com.

Attribution

Postgres, PostgreSQL, and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada.

Amazon Web Services and the “Powered by AWS” logo are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries.

Icons are provided by Icons8.

Keep reading

  • All Add-ons

Feedback

Log in to submit feedback.

Ziggeo BrandSSL

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences