Connecting to ClearDB from Heroku using Ruby on Rails on Cedar

Heroku got started as a Ruby on Rails PaaS provider, and ClearDB is no stranger to Ruby on Rails environments. This guide illustrates how to use the ClearDB add-on for Heroku as well as how to connect to ClearDB Dedicated Clusters.


Guide Overview
The Short Add-On Tutorial
The Complete Add-On Guide
– Prerequisites
– Getting Started
– Dual Masters, One Database Connection URL, Oh My!
– The Database URL
– Provisioning Your ClearDB Database
– Configuring Your Ruby Application To Use ClearDB
– Upgrading Your ClearDB Database
– Removing The ClearDB Add-On From Your Application
Connecting to ClearDB dedicated clusters from Heroku

1.0 Guide Overview

This tutorial is separated into two major parts – the first being the "short tutorial" where folks who are already familiar with the concepts of setting up Heroku addons can quickly add the ClearDB add-on, and the "complete guide", where folks can get a complete view as to what is required and how to set up the ClearDB Heroku add-on.

1.1 The Short Tutorial

Follow the following instructions and you'll have the ClearDB add-on installed and running in your app in no time!

  1. Run this: $ heroku addons:add cleardb:ignite –app (my_app_name_goes_here)
  2. Run this: $ heroku config
  3. Copy the CLEARDB_DATABASE_URL value and assign it to your DATABASE_URL value, like this:
    $ heroku config:add DATABASE_URL=(the_copied_value_of_CLEARDB_DATABASE_URL)
  4. Perform any git and/or rake tasks to update your application
    (such as restarting it) and your database should simply migrate
    to ClearDB and begin running.

1.2 The Complete Guide

1.2.1 Prerequisites

This tutorial assumes that you or someone on your team has adequate knowledge of MySQL's SQL database software as well as how to configure and use it in a RoR (Ruby on Rails) or the current Ruby environment of your choice in the Heroku cloud. It also presumes that you are familiar with basic Heroku command line functions, such as provisioning add-ons and using basic environment variables from within Ruby and Heroku to configure your applications to use MySQL.

1.2.2 Getting Started

During your development process, you will most likely be using a local MySQL instance to power your application. ClearDB uses native MySQL to power your MySQL applications, so you don't have to worry about any special data handling or transformation when working on your app. Using the ClearDB Heroku Add-On, ClearDB becomes part of your application stack once your application has been pushed into Heroku. The goal here is to ensure that moving into Heroku and ClearDB is a seamless transition from working in your local environment.

1.2.3 Dual Masters, One Database Connection URL, Oh My!

The ClearDB Heroku Add-On provisions your database on two "multi-master" database servers in two different Amazon EC2 regions to ensure absolute data availability. In our 1.0 add-on, this meant that you received two database connections. Now, with our custom SQL high availability routing technology, you get a single connection that automatically fails over to the secondary endpoint in the event of a failure, and will switch back to the primary master once service has been restored and the databases have re-synchronized.

The primary master node is located right next to Heroku, in Amazon's EC2 "US-East" region. The secondary master node is located in Amazon's EC2 "US-West" region for high availability purposes.

1.2.4 Database URL

Upon provisioning the ClearDB Heroku Add-On in your Heroku environment, you will receive a database URL, labeled "CLEARDB_DATABASE_URL". This URL is the connection to our CDBR endpoint, which automatically ensures that you’re connected to one of the two master instances in US-East and US-West, depending on service availability.

1.2.5 Provisioning Your ClearDB Database

To create your ClearDB database, simply type the following Heroku command: heroku addons:add cleardb:ignite –app my_app_name, replacing "my_app_name" with the name of your Heroku application. This will automatically provision your new ClearDB database for you and will return the database URLs to access it. You can also browse the Add-On catalog for ClearDB and simply click "Add" on the ClearDB Heroku Add-On to auto-provision your database for you.

1.2.6 Configuring Your Ruby Application To Use ClearDB

Configuring your Ruby Applications to use ClearDB is fairly simple – here are a couple of examples that you can use as a baseline reference for how to connect your application to use ClearDB:

1.2.6-A DataMapper Configuration

If you are using DataMapper, you can configure it to use the ClearDB MySQL instances like this:

require 'rubygems'
require 'data_mapper'

configure :development do
    DataMapper.setup(:default, 'mysql://localhost/my_dev_database')

configure :production do
    DataMapper.setup(:default, ENV['CLEARDB_DATABASE_URL'])

1.2.6-B Rails Configuration

To configure your Rails application to use ClearDB, simply set your DATABASE_URL environment variable to use one of the ClearDB URLs that you have available (preferrably the "A" URL). Heroku should do the rest by auto-generating a new database.yml file for your application which will connect your application directly to your ClearDB database.

To set your DATABASE_URL to the value of CLEARDB_DATABASE_URL, simply issue the following heroku command:

heroku config:add DATABASE_URL=(the copied value of the CLEARDB_DATABASE_URL config variable)

For example:

heroku config:add DATABASE_URL=mysql://

Or, if you're using a more recent version of Rails, you can use a URL similar to the previous example, but this time with the "mysql2" scheme in place. For example:

heroku config:add DATABASE_URL=mysql2://

At this point Heroku should do the rest with regards to rebuilding your database.yml file and connecting you to your new ClearDB database.

1.2.7 Upgrading Your ClearDB Shared Database

Upgrading your ClearDB database to a larger plan is really easy and only takes a moment. Use the addons:upgrade Heroku command, like this:

heroku addons:upgrade cleardb:scream

Learn more about our add-on service plans by going to

1.2.8 Removing the ClearDB Add-On For Heroku

If you want to remove our Heroku Add-On (hopefully in order to move to a dedicated cluster!), simply use the following heroku command:

heroku addons:remove cleardb

Learn more about all Heroku addon commands by going to
the Heroku devcenter.

1.3 Connecting to ClearDB Dedicated Clusters From Heroku

Connecting to a ClearDB dedicated cluster from Heroku is very similar to how one would connect to ClearDB from the ClearDB add-on for Heroku. The difference is how dedicated database clusters are provisioned. Once you have purchased a ClearDB dedicated cluster from us and have received your database connection information, you will need to construct a database URL that Heroku understands, such as this:


Once you have constructed your database URL, you can assign it to the Heroku DATABASE_URL environment variable as illustrated in section 1.2.6-B. From there, simply restart your apps on Heroku and your application (and Heroku) should recognize the new database.

1.4 Conclusion

Heroku is an exciting platform for which to operate Ruby and Rails applications. With ClearDB, it’s turned into a powerful, highly available service that can keep your apps running smoothly and effectively.

Developer Resources