PostgreSQL Settings in the Boxfile
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
database1: 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:
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 database1: type: postgresql version: 9.4
Topology defines the service's architecture and in what ways it can scale. PostgreSQL supports the following topologies:
More information can be found in the Service Topologies doc.
database1: 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 (irc.freenode.net #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.
Table of Contents
If you have any questions, suggestions, or corrections, let us know.