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.
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 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.
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.
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:
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')
end
configure :production do
DataMapper.setup(:default, ENV['CLEARDB_DATABASE_URL'])
end
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://adfl12312:hgfdkvdgw@us-cdbr-auto-dca-01.cleardb.com/heroku_argtwreq42t4t
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://adfl12312:hgfdkvdgw@us-cdbr-auto-dca-01.cleardb.com/heroku_argtwreq42t4t
At this point Heroku should do the rest with regards to rebuilding your database.yml file and connecting you to your new ClearDB 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 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:
mysql2://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 Ruby and Rails applications. With ClearDB, it's turned into a powerful, highly available service that can keep your apps running smoothly and effectively.