Heroku Postgres and Heroku Private Spaces

Last updated 12 September 2017

This article explains the differences between Heroku Postgres provisioning, plans, and connections when used in Private Spaces as compared with using Postgres in the Common Runtime. If you would like to learn how to migrate an existing database into a Private Space, see the Migrating Heroku Postgres Databases to Private Spaces article.

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

Heroku Postgres can run within a Private Space or Shield Space, with a similar developer experience as on the Common Runtime. Many of the same CLI commands and web interfaces will work for private & shield Heroku Postgres databases. Private & Shield Heroku Data add-ons are not accessible to applications at build-time. We advise you to eliminate the dependency on your private data store, use a public Heroku Data plan, or contact support for guidance.

Provisioning

Heroku Postgres has a series of plans that are only meant for Private and Shield Spaces. The private & shield tier plans are the only plans that can be provisioned inside the isolated network environment. Attempts to create databases from the hobby, standard, or premium tiers, against applications in Private or Shield spaces is unsupported.

Create a new database

Many buildpacks will create a database as part of the build process. If the application that’s being created is within a Private Space, unless a database already exists for that application, the lowest available private plan will be used when creating the database. For a list of the currently available plans, see the plans section.

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
• Database metrics published to application log stream
• High availability
• Automatic encryption-at-rest of all data written to disk.

External connections

Unlike the Heroku Postgres databases in our hobby, standard, and premium tiers, private databases cannot be accessed via a local computer. For access to the private databases, you must use the available Heroku Postgres CLI commands. This ensures that you have the correct authorization to connect to the database across the isolated network boundary.

If a direct connection must be made to a Heroku Postgres database from outside the private space boundary, the Trusted IPs feature of Private Spaces can be used to enable the connection. For Trusted IPs to be used for direct connections, the Private Space must be whitelisted by Heroku to enable the functionality. An email can be sent to postgres@heroku.com to discuss use cases and ability to have your private space included. More details on Trusted IPs for data services (Heroku Postgres, Heroku Redis and Apache Kafka on Heroku) can be found in the Private Spaces documentation.

Using the CLI

The ability to connect to private databases is integrated directly in to the Heroku CLI and all of the commands available for the other types of databases are available for private databases.

For more information on the available CLI commands for Heroku Postgres, see the main Heroku Postgres article.

Shield Tier Plans

Heroku Postgres offers a set of plans for Shield Spaces. The shield tier is designated 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
• 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 are not possible. Encrypted connections are always enforced.
• Dataclips cannot connect to shield databases
• shield databases does not allow connections via heroku pg:psql from outside the Private Space
• shield databases are monitored by additional intrusion detection and host scanning mechanisms
• PGBackups will not work with shield databases

Connecting to shield database via terminal

Heroku CLI command line tools like heroku pg:psql will not work when connecting to the database from your local machine because arbitrary ingress rules aren’t allowed. Instead, a database connection should 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

All connections to a private database must be made with TLS/SSL. See the connection documentation for your language in the main Heroku Postgres article.