We removed our free Sandbox April 25th.
You can read more on our blog.

PostgreSQL and PostGIS

Warning

This service does not scale for High Availability on the dotCloud Platform. Please do not use this service if your application requires High Availability.

Can your application continue to run without this service? If not, then you should choose an alternative, or spend more time planning how your application will handle outages in this service during machine reboots or other interruptions to this service.

Suggested alternatives for High Availability

Use This Instead of This
MySQL or MongoDB PostgreSQL, PostGIS
Elastic Search (custom) Solr

Note

CLI Command examples on this page are always provided without the --application (shorthand -A) argument, assuming you’re running these commands in a connected folder (at creation or using the dotcloud connect command). For more details on connected folders, see Migrating to the CLI 0.9.

dotCloud features PostgreSQL 9.0. You can also request a PostGIS enabled PostgreSQL for use in your geographic applications.

Basics

If your application requires a PostgreSQL database, all you need to do is add the following lines to your dotcloud.yml Build File (dotcloud.yml):

data:
  type: postgresql

If you want to have a PostgreSQL server with PostGIS extensions, specify postgis instead:

data:
  type: postgis

Note

You can give your database or cache service any name you like instead of “data”. If for some reason your application needs multiple databases, you can either use multiple independant services (by repeating the database section multiple times in dotcloud.yml, each with a different name instead of just “db”), or create multiple users and databases inside one single service. The first option (multiple services) will bring more resources, but keep in mind that when you go to production, this will generally incur higher costs as well.

Your data service will be globally available. This means that you can use it with applications running on other platforms.

If for some reason, you want to use dotCloud just to deploy a standalone data service, create a two-line “dotcloud.yml” file in an empty directory, and from this directory, just run:

dotcloud create mynicedb
dotcloud push
dotcloud info data

In less than one minute, your data service will be up and running, and the dotcloud info command will show its connection credentials.

Configure Your Application

There are two ways to configure your app to use your new data service:

  • manually, by hard-coding the host, port, user and password;
  • automatically, by retrieving those parameters from the Environment File.

Manual Configuration

Check your service parameters using dotcloud info:

dotcloud info data

You can use the “root” user, or create your own users if you prefer. If you want to create the user “joe”, run the following command:

dotcloud run data -- createuser joe --pwprompt

This will create the user “joe” and prompt you for a password for this new user. Be sure to pick a secure password.

You can also decide to use the default “template1” database, or create your own. If you want to create your own database, you can run the following command:

dotcloud run data -- createdb mydb

And, if you want it to belong to the “joe” user created in the previous step:

dotcloud run data -- createdb -O joe mydb

Using environment.json

When your application is built by the dotCloud platform, a file named environment.json is created in the home directory of each of your services.

This file contains a JSON-formatted dictionary with most of the configuration information of the services in your stack. You can use it to retrieve the host, port, and password, of your databases, caches, and so on.

You will find snippets of code to retrieve the connection information of your databases in the Environment Guide.

Your mynicedb.data service will expose the following variables:

  • DOTCLOUD_DATA_SQL_HOST
  • DOTCLOUD_DATA_SQL_LOGIN
  • DOTCLOUD_DATA_SQL_PASSWORD
  • DOTCLOUD_DATA_SQL_PORT
  • DOTCLOUD_DATA_SQL_URL

Note that DATA will be replaced by the (upper-cased) name of your service.