Last updated October 11, 2024

This article explains considerations for Heroku Postgres provisioning, plans, and connections that are specific to Private Spaces. If you have an existing Heroku Postgres database on the Common Runtime and you want to migrate it into a Private Space, see Migrating Heroku Postgres Databases to Private Spaces.

Heroku Private Spaces are dedicated environments for running applications within an isolated network. This means that every part of an application’s stack, including the dynos, data stores, and third-party add-ons, are contained within this isolated environment.

Heroku Postgres can run within a Private Space or Shield Space with a developer experience similar to that of the Common Runtime. Many of the same CLI commands and web interfaces work identically.

Provisioning

Private and Shield Spaces each have their own set of Heroku Postgres plans that are unique to that type of space. You can provision databases from the Essential, Standard, or Premium tiers in a space and specify the region with the --region flag. Those add-ons won’t be automatically networked with your private space. The us-east-1 region is the default if you don’t specify a region. You can only provision Essential-tier databases in the us-east-1 or eu-west-1 regions.

Create a New Database

Many buildpacks provision a database as part of the Heroku build process. If you create an app within a Private or Shield Space, the smallest available private or shield plan is used by default when provisioning. See the following for full lists of available Private and Shield tier plans.

Private Heroku Postgres databases can be provisioned via the CLI:

$ heroku addons:create heroku-postgresql:private-4 -a private-sushi

Depending on the region and the type of database being created, the provisioning process can take up to 10 minutes before the database is available for use.

Private Tier Plans

Heroku Postgres offers a set of plans for Private Spaces. The private tier is designed for production applications that can tolerate up to 15 minutes of downtime in any given month. All private-tier databases include:

• No row limits
• Increasing amounts of in-memory cache
• Fork and follow support
• Rollback up to 7 days
• Database metrics published to application log stream
• High availability
• Automatic encryption-at-rest of all data written to disk

Shield Tier Plans

Heroku Postgres offers a set of plans for Shield Spaces. The shield tier is designed for production applications that can tolerate up to 15 minutes of downtime in any given month. All shield tier database include:

• No row limits
• Increasing amounts of in-memory cache
• Fork and follow support
• Rollback up to 7 days
• Database metrics published to application log stream
• High availability
• Automatic encryption-at-rest of all data written to disk

Shield tier databases differ from private tier databases and can only be used in conjunction with a Shield Space. Shield Heroku Postgres databases are meant for situations where meeting compliance is a goal of your application and business. Shield databases also have the following feature sets and restrictions:

• Non-TLS connections from dynos to shield databases aren’t possible. Encrypted connections are always enforced.
• Dataclips can’t connect to shield databases
• shield databases don’t allow connections via heroku pg:psql from outside the Private Space
• Direct access via “Trusted IPs” isn’t allowed for shield databases from outside the Private Space
• shield databases are monitored by additional intrusion detection and host scanning mechanisms
• PGBackups don’t work with shield databases
• shield databases can’t have forks or followers in non-shield spaces.
• pg:diagnose and the Diagnose tab of the Heroku Data dashboard are unavailable

Connecting to Shield Database via Terminal

Heroku CLI command line tools like heroku pg:psql don’t work when connecting to the database from your local machine because arbitrary ingress rules aren’t allowed. Instead, a database connection must be made via a Heroku Dyno assuming that the primary database is using the DATABASE_URL config var:

$ heroku run bash
Running bash on ⬢ sushi... up, run.3032 (1X)

~ $ psql $DATABASE_URL
psql (9.6.1, server 9.6.2)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
Type "help" for help.

d8vbabiotc9412=>

Connecting to the Database

Programming Language Specifics

All connections to a private database must be made with TLS/SSL. See the Heroku Postgres connection documentation, which has examples for Java, Ruby, JRuby, Python, Go, PHP, and Node.js.

Connecting to Amazon VPCs via AWS PrivateLink

You can use PrivateLink to connect to a Private or Shield Heroku Postgres Database from an Amazon VPC. See Connecting to a Private or Shield Heroku Postgres Database via PrivateLink for details.

Connecting via mTLS

You can use Mutual TLS to create a secure and mutually authenticated channel between an external resource and a Heroku Postgres database running in a Private Space or a Shield Private Space. See Connecting to a Private or Shield Heroku Postgres Database from an External Resource for details.

Connecting from Heroku Runtimes

Connections to a database instance with a private plan can only be made within a private space. Connections can’t be made from other private spaces (and private space databases can’t be attached across space boundaries), or from the common runtime.

If you must connect to a database from a different private space or from the Common Runtime, you want a database instance with a non-private plan, which lives in the Common Runtime.

You can also use mTLS to connect to a database from a different private space. See Connecting to a Private or Shield Heroku Postgres Database from an External Resource for details.

If you’re connecting to a database in one region from a private space in another region, there can be increased latency.

Using the CLI

Unlike the Heroku Postgres databases in our other tiers, you can’t access Private and Shield databases via a local computer.

For access to a private plan Heroku Postgres database, you can use heroku pg:psql. This ensures that you have the correct authorization to connect to the database across the isolated network boundary.

For access to a shield plan Heroku Postgres database, you can’t use heroku pg:psql and can only access the database via a dyno in your shield space.

Trusted IPs for Data

Trusted IPs for data are a feature of Private Plans in Private Spaces. Databases in Shield Private Spaces can’t use Trusted IPs.

If you must make a direct connection to a Heroku Postgres private plan database from outside the Private Space boundary, use the Trusted IPs feature of Private Spaces to enable the connection. To use Trusted IPs for direct connections, Heroku must allowlist your Private Space to enable the functionality. Open a support ticket to discuss use cases and ability to have your Private Space included. See more details on Trusted IPs for data services Heroku Postgres, Heroku Key-Value Store, and Apache Kafka on Heroku in the Private Spaces documentation.