This guide illustrates how to use the ClearDB add-on for Heroku as well as how to connect to ClearDB Dedicated Clusters using Python.
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.
Follow the following instructions and you'll have the ClearDB add-on installed and running in your Rails app in no time!
That's it!
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.
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.
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.
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.
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.
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.
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 http://addons.heroku.com/cleardb.
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.
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:
mysql://username:password@cleardb-cdbr-endpoint.cleardb.com/database_name
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.
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.