In the previous two tutorials we set up a PHP application on AppFog and made sure we could update it locally. Then we took that a step further and added a new page and a means to navigate between them. In this our third tutorial we’re going to be adding a database service to our app and then connecting to it to see that all is well. This is in preparation for the 4th tutorial in the series where we’ll start putting in real live Mxit messaging functionality that you can use anywhere! Let’s get started. 

Step 1 - Data services and AppFog

Go to your AppFog control panel and select your application. Remember that in this tutorial, we called it "testappmxt" and this is what it looks like from the control panel: 

Figure 1: An overview of your app in AppFog's Control Panel.  

Now click on the Services tab on the left.

Figure 2: Clicking on "Services" on the left-side menu to add a service.

We don’t have any database services linked up to our app yet so let’s fix that. Select MongoDB, name the service "testappmxt-mongo" and then click the "Create" button.

In a few seconds, AppFog will allocate us a Mongo database and bind it to our running application. When this binding is complete, you should see something like this:

Figure 3: Binding a database to your App, using MongoDB.

So now that we have a database service running and available to our app, the next step is to access it and test that it works.

Step 2: Connecting to the database

In the previous tutorials, we uploaded our application to AppFog using the ‘af’ command and we’re going to use it again to connect to our running instance over an encrypted tunnel. For an overview of the process and the prerequisites of tunneling, have a look at AppFog’s documentation here: https://docs.appfog.com/services/tunneling.

It’s pretty straightforward: install a local instance of the database client we’ll be using (in our case mongo), and a helper application called Caldecott which takes care of the actual tunneling. Then go into your working directory and log in as usual:

/mxit/testappmxt$ af login
Attempting login to [https://api.appfog.com]
Email: your-email-address@example.com
Password: ************
Successfully logged into [https://api.appfog.com]

Now you can query AppFog about running services: 

/mxit/testappmxt$ af services
============== System Services ==============
+------------+---------+-------------------------------+
| Service    | Version | Description                   |
+------------+---------+-------------------------------+
| mongodb    | 1.8     | MongoDB NoSQL store           |
| mysql      | 5.1     | MySQL database service        |
| postgresql | 9.1     | PostgreSQL database service   |
| rabbitmq   | 2.4     | RabbitMQ message queue        |
| redis      | 2.2     | Redis key-value store service |
+------------+---------+-------------------------------+
=========== Provisioned Services ============
+------------------+---------+--------+
| Name             | Service | In     |
+------------------+---------+--------+
| testappmxt-mongo | mongodb | eu-aws |
+------------------+---------+--------+
And there’s our mongo service. Let’s connect to it:
maverick@leviathan:~/work/mxit/testappmxt$ af tunnel testappmxt-mongo
Getting tunnel connection info: OK
Service connection info: 
  username : your-user-name
  password : your-password
  name     : db
  url      :mongodb://672f8a00-be51-4018-9991-10.10.0.1:25410/db
  infra    : eu-aws
Starting tunnel to testappmxt-mongo on port 10000.
1: none
2: mongo
3: mongodump
4: mongorestore
Which client would you like to start?: 2

Step 3: Testing things out

Choose option 2 and you’ll be presented with something like this:

Launching 'mongo --host localhost --port 10000 -u your-user-name -p your-password db'
MongoDB shell version: 2.0.6
connecting to: localhost:10000/db

And we’re in! We’ll be looking at the syntax for MongoDB in a bit more depth next tutorial but for now you can have a read through at: http://docs.mongodb.org/manual/tutorial/getting-started/ to get started. Let’s test it quickly: 

> u = { mxitid: 'a-mxit-user' }
{ "mxitid" : "a-mxit-user" }
> db.mxitusers.insert(u)
> v = {mxitid: 'another-mxit-user'}
{ "mxitid" : "another-mxit-user" }
> db.mxitusers.insert(v)
> show collections
mxitusers
system.indexes
system.users
> db.mxitusers.find()
{ "_id" : ObjectId("515e3b27c54c33504dbcb9f4"), "mxitid" : "a-mxit-user" }
{ "_id" : ObjectId("515e3b4bc54c33504dbcb9f5"), "mxitid" : "another-mxit-user" }
> 

What's Next?

In Tutorial 4, we’ll be using our Mongo database to store some Mxit user ids and that will allow us to leverage Mxit’s Messaging API. See you then!