An official website of the United States government US flag signifying that this is a United States federal government website

Relational databases (aws-rds)

Relational databases (aws-rds)

If your application uses relational databases for storage, you can use the AWS RDS service to create a database instance.


Plan Name Description Price
shared-psql Shared PostgresSQL database for prototyping (no sensitive or production data) Free
medium-psql Dedicated medium RDS PostgreSQL DB instance Will be paid per hour + storage
medium-psql-redundant Dedicated redundant medium RDS PostgreSQL DB instance Will be paid per hour + storage
large-psql Dedicated large RDS PostgreSQL DB instance Will be paid per hour + storage
large-psql-redundant Dedicated redundant large RDS PostgreSQL DB instance Will be paid per hour + storage
shared-mysql Shared MySQL database for prototyping (no sensitive or production data) Free
medium-mysql Dedicated medium RDS MySQL DB instance Will be paid per hour + storage
medium-mysql-redundant Dedicated redundant medium RDS MySQL DB instance Will be paid per hour + storage
large-mysql Dedicated large RDS MySQL DB instance Will be paid per hour + storage
large-mysql-redundant Dedicated redundant large RDS MySQL DB instance Will be paid per hour + storage
medium-oracle-se1 Dedicated medium RDS Oracle SE1 DB; available by request via support Will be paid per hour + storage

Note: the medium-oracle-se1 plan is only available by request because AWS is deprecating Oracle SE1. AWS GovCloud expects to support Oracle SE2 in July 2017; at that point, we’ll add a corresponding service plan and make it available to all users without requesting access.


Shared instances are free. Simple and redundant instances will have pricing per hour and per GB per month. Learn more about managed service pricing.


Name Required Description Default
storage Number of GB available to the database instance 10

Create an instance

To create a service instance run the following command:

cf create-service aws-rds medium-psql my-db-service

If you want to specify the storage available to the instance:

cf create-service aws-rds medium-psql my-db-service -c '{"storage": 50}'

Bind to an application

To use the service instance from your application, bind the service instance to the application. For an overview of this process and how to retrieve the credentials for the service instance from environment variables, see Bind a Service Instance and the linked details at Delivering Service Credentials to an Application.

In short, cf bind-service will provide a DATABASE_URL environment variable for your app, which is then picked up by the restage.

The contents of the DATABASE_URL environment variable contain the credentials to access your database. Treat the contents of this and all other environment variables as sensitive.

Access the data in the database

There are currently two ways to access the database directly.

  1. The cg-migrate-db plugin. It is a self contained executable which will interactively assist with accessing the data in the database. It supports accessing data from different types of databases.
  2. Manually accessing the database. This way requires manually downloading the tool(s) needed to access the database.

cg-migrate-db plugin

You can access the data in your database via the cg-migrate-db plugin. See the repository for instructions on how to install the plugin, backup data, import data, download a local copy of the data, and upload a local copy of the data.

Manually access a database

Using cf ssh

To access a service database, use the cf-service-connect plugin.


Create backup

The instructions below are for PostgreSQL, but should be similar for MySQL or others.

First, connect to an instance using the cf-service-connect plugin:

$ cf connect-to-service --no-client ${APP_NAME} ${SERVICE_NAME}
Host: localhost
Port: ...
Username: ...
Password: ...
Name: ...

Without closing the SSH session managed by the cf-service-connect plugin, create the backup file using the parameters provided by the plugin:

$ pg_dump postgresql://${USERNAME}:${PASSWORD}@${HOST}:${PORT}/${NAME} -f


Documentation for using scp and sftp

On your local host:

Get your app’s GUID:

$ cf app {app name} --guid

Obtain a one-time authorization code:

$ cf ssh-code

Run sftp or scp to transfer files to/from an application instance. You must specify port 2222 and supply the app GUID and instance number. Use the one-time authorization from above as the password. The username format is cf:GUID/INSTANCE.

For example, to connect to instance 0 of the application with GUID 0745e60b-c7f3-49a7-a6c2-878516a34796:

$ sftp -P 2222 cf:0745e60b-c7f3-49a7-a6c2-878516a34796/
cf:0745e60b-c7f3-49a7-a6c2-878516a34796/'s password: ******
Connected to
sftp> get
sftp> quit

Restore to local database

Load the dump into your local database using the pg_restore tool. If objects exist in a local copy of the database already, you might run into inconsistencies when doing a pg_restore. This pg_restore invocation does not drop all of the objects in the database when loading the dump.

$ pg_restore --clean --no-owner --no-acl --dbname={database name}


Every RDS instance configured through is encrypted at rest.

Rotating credentials

You can rotate credentials by creating a new instance and deleting the existing instance. If this is not an option, email support to request rotating the credentials manually.

The broker in GitHub

You can find the broker here: