Connecting to ClearDB from Heroku using Python

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


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 Python 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 Python 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 Python Application To Use ClearDB

To begin to use Python with ClearDB on Heroku, check out Heroku’s documentation on using Django with MySQL Databases. While it’s labeled as a PostgreSQL only introduction, it also covers how to do the same configuration and setup using MySQL, and the beauty of how Django works is that most of the actual work for setting up Django with MySQL is done internally through Django’s database abstraction model.

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. 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 Python applications. With ClearDB, it’s turned into a powerful, highly available service that can keep your apps running smoothly and effectively.

Developer Resources