PostgreSQL Settings in the Boxfile

Last Updated May 2015

The Boxfile is a yaml config file that allows you to custom-configure your app's environment. Settings typically set in the postgresql.conf are handled here. The following configuration options available in the Boxfile allow you to tailor-fit the build of your PostgreSQL database specific to your needs. After reading this, you should understand how to:

  • How to customize your PostgreSQL build
  • Bask in the awesomeness of PostgreSQL and Pagoda Box

Overview of PostgreSQL Boxfile Settings YAML

    type: postgresql
    version: 9.4
    stability: beta
    topology: single

PostgreSQL Configuration Options

Type & Version

When configuring a PostgreSQL service in your Boxfile, you must define the type of the service as postgresql. You can also specify the version of PostgreSQL to load into your database service. The following version(s) are available:

  • 9.4

The specific patch level is determined by the "stability" config.

PostgreSQL Version Defined on Create

PostgreSQL versions cannot be changed after the service is created. To use a different version, you'll have to create a new PostgreSQL service.

postgresql type & version YAML

  # default setting
    type: postgresql
    version: 9.4

Topology defines the service's architecture and in what ways it can scale. PostgreSQL supports the following topologies:

  • Single

  • Redundant

More information can be found in the Service Topologies doc.

topology YAML

    type: postgresql
    topology: single

Request PostgreSQL Boxfile Configs

One of the many benefits of using PostgreSQL is that it doesn't require much configuration. The project itself is finely tuned. However we know there are settings that users like to tweak. If there's a setting you'd like to modify that is typically handled in the postresql.conf, please let us know by submitting a ticket or requesting it in our IRC channel ( #pagodabox).

Boxfile Modifications Only Take Affect After a New Build

Whenever changes are made to a PostgreSQL service's configuration in the Boxfile, those changes will not apply until the service is rebuilt. By default, PostgreSQL services are not rebuilt on deploy. However, there are three options for rebuilding your service:

Enable Rebuild on Deploy

In your app dashboard, under Dev Config > Deployment Options, you can enable the option to have data services rebuild on deploy whenever changes to the service's Boxfile config are detected.

Rebuilding data services on deploy will increase deploy times, but only when changes to the service's config are detected.


Any time you scale a PostgreSQL Service, a new instance or instances are provisioned, data is migrated, requests are routed to the new instance(s) and old instances decommissioned. The new instances are built using the modified settings in your Boxfile.


In your dashboard, click on your PostgreSQL service to expand it's options. Each data service has a "Repair" option.

"Repairing" your service will provision a new instance (or instances) based on the settings in your Boxfile, migrate data to the new instance, then reroute requests away from the old instance to the new.

New Builds Require Data Migrations

Data migrations are required during a rebuild. Your service will temporarily go offline during the migration process. The Data Migrations During Scaling & Repairs doc has more information.

If you have any questions, suggestions, or corrections, let us know.