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

Relational databases (RDS)

Relational databases (RDS)

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


Plan Name Description Software Version Price
shared-psql Shared PostgreSQL database for prototyping (no sensitive or production data) 9.4.7 Free
medium-psql Dedicated medium RDS PostgreSQL DB instance 9.6.10 Will be paid per hour + storage
medium-psql-redundant Dedicated redundant medium RDS PostgreSQL DB instance 9.6.10 Will be paid per hour + storage
large-psql Dedicated large RDS PostgreSQL DB instance 9.6.10 Will be paid per hour + storage
large-psql-redundant Dedicated redundant large RDS PostgreSQL DB instance 9.6.10 Will be paid per hour + storage
shared-mysql Shared MySQL database for prototyping (no sensitive or production data) 5.6.27 Free
medium-mysql Dedicated medium RDS MySQL DB instance 5.7.21 Will be paid per hour + storage
medium-mysql-redundant Dedicated redundant medium RDS MySQL DB instance 5.7.21 Will be paid per hour + storage
large-mysql Dedicated large RDS MySQL DB instance 5.7.21 Will be paid per hour + storage
large-mysql-redundant Dedicated redundant large RDS MySQL DB instance 5.7.21 Will be paid per hour + storage
medium-oracle-se2 Dedicated medium RDS Oracle SE2 DB Will be paid per hour + storage


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

Shared instances are available in sandbox spaces.


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}'

Instance creation time

Dedicated RDS instance provisioning can take anywhere between 5 minutes and 60 minutes. During instance provisioning, the results of cf services or cf service SERVICE_NAME will show status as created, as in the following example:

> cf services
name                 service   plan                bound apps   last operation
test-oracle          aws-rds   medium-oracle-se2                create succeeded

The last operation value of create succeeed may lead you to think the database is ready to use. This is misleading. Instead, the last operation indicates the API call to create the database has succeeded, not that provisioning has completed. To determine if a database is ready to use, test if you can create a service key. For example, test-oracle is not yet ready in this case:

cf create-service-key test-oracle test-oracle-ok
Creating service key test-oracle-oke for service instance test-oracle as
Server error, status code: 502, error code: 10001, message: Service broker error: There was an error binding the database instance to the application. Error: Instance not available yet. Please wait and try again..

If the response is OK instead of FAILED then your database is ready to use.

The team aims to provide clearer status indicators in a future release of our service broker.

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}


For shared plans (shared-psql and shared-mysql), RDS does not back up your data. For dedicated plans, RDS automatically retains daily backups for 14 days. These backups are AWS RDS storage volume snapshot, backing up the entire DB instance and not just individual databases. You can email support to access that backup if you need to as a separate RDS instance. You will be responsible for exporting and importing the data from this snapshot into your existing database. You can also create manual backups using the export process described above. In general, you are responsible for making sure that your backup procedures are adequate for your needs; see CP-9 in the SSP.


Every RDS instance configured through is encrypted at rest. We use the industry standard AES-256 encryption algorithm to encrypt your data on the server that hosts your RDS instance. The RDS then handles authenticating access and decrypting your data, with minimal performance impact and without requiring you to modify your applications.

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.

Version information

The software versions listed in the table above are for new instances of those plans.

New instances of dedicated RDS plans use the latest database version available from AWS RDS GovCloud (US) at the time. New instances of shared plans may use older database versions.

The PostgreSQL and MySQL plans are configured to automatically upgrade currently-running dedicated instances to the most recent compatible minor version available via AWS RDS GovCloud (US).

For Oracle plans, minor upgrades are not automatic. To upgrade an existing Oracle database instance, contact support and schedule a maintenance window for the upgrade to take place.

The broker in GitHub

You can find the broker here: