Database Service Settings in the Boxfile

Last Updated February 2015

Database services are actual databases avaialable on Pagoda Box. This doc covers all of the Boxfile configuration options available for database services.The Boxfile is responsible for much of the granular control and streamlined workflow available on Pagoda Box. After reading this doc, you will be familiar with:

  • Configuring database services
  • What options are available in the Boxfile

Overview of Database Boxfile Options YAML

    name: db-name
    type: mysql
    version: 5.6
    stability: production

Database Service Config Options

MySQL Settings

You can see all the MySQL settings available in the MySQL, MariaDB, & Percona Settings in the Boxfile Doc.

PostgreSQL Settings

You can see all the PostgreSQL settings available in the PostgreSQL Settings in the Boxfile Doc.

MongoDB Settings

You can see all the MongoDB settings available in the MongoDB Settings in the Boxfile Doc.


Creating a custom name for your database service will act as a quick reference for your database in your App Dashboard. If you have multiple database services, custom names will come in handy. If you do not define a custom name, Pagoda Box will generate a cache name for you.

Note: This will not set the "name" connection credential for your service.

name YAML

    name: buela

This one is fairly self-explanatory. What type of database you need completely depends on your app. The following database types are available:

  • mysql

  • mariadb

  • percona

  • postgresql

  • mongodb

You Must Include a Database Type

A database type must be included in your Boxfile config. If no type is specified, the service will not be created on deploy.

type YAML

    type: mysql

The "version" config specifies which version of the database type to use. Only the major and minor version should be specified. The patch level is determined by the "stability" config.

Database Version Defined on Create

Due to version compatibility constraints, database versions cannot be changed after the service is created. To use a different version, you'll have to create a new database and manually migrate data.

version YAML

    type: mysql
    version: 5.5

The "stability" config allows you to specify which patch level of your service "version" you'd like to use. There are three stability options:

  • alpha

  • beta

  • production

Alpha & Beta Versions

Alpha and beta versions are for bleeding edge developers who want nothing but the latest releases of languages. Please note however, Pagoda Box does not guarantee the compatibility of these versions with the Pagoda Box infrafstructure or your app. These are "builds-in-progress," and using them is done at your own risk. Pagoda Box will only provide support for infrastructure-compatibility issues related to these specific versions. No app-compatibility support will be provided.

stability YAML

    type: mysql
    version: 5.5
    stability: production

Automated Environment Variables

Anytime you create a database, we automatically create Environment Variables for each of your database credentials.

Boxfile Modifications Only Take Affect After a New Build

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

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 database, a new instance or instances are provisioned, data is migrated (if possible), requests 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 database 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 (if possible), 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. More details in the Data Migrations During Scaling & Repairs doc.

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