ClearDB Logo
Home » Developers » PaaS Connections » Heroku » Connecting to ClearDB from Heroku using Node.js

This guide illustrates how to use the ClearDB add-on for Heroku as well as how to connect to ClearDB Dedicated Clusters using Node.js.


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 Rails 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 maven tasks to update your application (such as restarting it) and your database should simply migrate to ClearDB and begin running.

That's it!

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 Node.js 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 Node.js 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 Node.js Application To Use ClearDB

To begin to use Node.js with ClearDB on Heroku, it's probably best to reference the documentation that's provided by both Heroku as well as Node.js DB Binding authors. The Node.js Database Binding folks have an excellent tutorial on how to set up Node.js to work with MySQL.

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, simply fill in the connection details as received from ClearDB in your Node.js source.

1.4 Conclusion

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