Developing with CouchDB on Android

13th Feb 2011

This article is out of date, please visit the Android Couchbase github for newer instructions.

So you know why CouchDB on mobile is an awesome fit, but getting CouchDB working on the device is only the first step, for it to be useful CouchDB needs to provide an easy and convenient way to be used on mobile devices. This is the first in a series of introductions to CouchDB on Android.

In this post I will take a very basic CouchApp and turn it into a native Android App. If you arent familiar with CouchApps, please check out couchapp.org. The github sources are up for the couchapp and related android project

Warning CouchDB on Android is currently in beta, the API’s may change in future and you should always backup any data seperately.

Ugh, Install Dependencies

Install the Android SDK
Install CouchApp
Download libcouch-android, tgz or git
Install CouchDB on your device / emulator

Lets Get Started

First you should open a log viewer this allows you to view logs produced by CouchDB and your browser.

$ adb logcat

If you havent already started CouchDB on the device, do so now. once you see a “CouchDB Running” notification then run the following command in your shell:

$ adb forward tcp:5985 tcp:5984

You can now access CouchDB on your device via your computer @ 127.0.0.1:5985/_utils

Now you need to open the libcouch-android project in eclipse (File > New Project > Android Project > Open from existing directory and browse to the directory you downloaded libcouch-android)

Then create a new Android Project, File > New Project > Android Project

Open AndroidManifest.xml and enter:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

to make sure your app can communicate with Couch’s REST API (example here)

Add libcouch-android as a library to your Application, you can do this by right clicking your new application in the project manager, picking Properties > Android and choosing libcouch-android

Copy the source of ExampleCouchApp.java into your main activity MyApp/src/com/myname/myapp/MyApp.java(remember to preserve your package + class name) and set the bootStrapDatabases + appToLaunch variables as instructed, here is a working example

Drag and drop this json file to the assets directory, this json can be created for any couchapp by using the command

$ couchapp push --export > filename.json

Your App should be ready to go! Click on the green Run button in eclipse and your application should be loaded on your phone, if you run in to any problems then check the output of $ adb logcat, below is an example of what the project should look like:

Well done on your first Android + CouchDB App :) I have started compiling a list of frequently asked questions below to help you as you start making your own Android CouchApps, if you have problems or there is anything I havent covered, please get in touch with me dale@couchbase.com or @daleharvey I would also love to hear from you if you are using CouchDB to build mobile apps, Have fun and Relax.

Comment on Hacker News

FAQ – Developing on android

How do I access CouchDB on my computer

$ adb forward tcp:5985 tcp:5984

Will let you access CouchDB via http://127.0.0.1:5985/_utils

How do I view the CouchDB / Console logs

$ adb logcat

Something broke?

That isnt a question, but please email me at dale@couchbase.com with as much information as possible. The output from $ adb logcat is extremely useful.

How do I build CouchDB for Android myself?

You dont need to build CouchDB yourself to program against it, but if you really want to then there are instructions on the CouchDB wiki

Much thanks to Matt Adams.

How do I use CouchApp to push to my phone?

The same way you push to any other CouchDB, you need to have set up forwaring first, my .couchapprc file looks like:

{
  "env" : {
    "default" : {
      "db" : "http://myname:mypass@127.0.0.1:5984/couchnotes"
    },
    "android" : {
      "db" : "http://com_arandomurl_couchnotes:pass@127.0.0.1:5985/couchnotes-org_android_couchnotes"
    }
  }
}

I tried to create a database with name X and it doesnt exist?

You cant directly create databases as they may conflict with other applications, your databases will be created with your packagename appended (with periods replaced by underscores) so the database created for CouchNotes is names couchnotes-com_arandomurl_couchnotes

How do I find out the credentials to CouchDB databases?

When you create a database you provide a password, a user is created with the username being the package name of your app with periods replaced with underscores (for example com_arandomurl_couchnotes) and they are set as admin on any databases you create.

CouchUtils.java provides a readOrGeneratePass function to help generate and store a password, you can find the generated password by running:

adb shell cat /data/data/com.myname.myapp/files/com_myname_myapp.passwd

Click on the menu button while futon is open and select Admin Password

Is my data really secure?

No, although the SDK provides seperation between applications, currently Android CouchDB stores all data on the SD Card of your phone due to the size of the data. Other applications can access your data directly though the SD Card.

I want a native app, not a CouchApp

The process for building a native application that uses CouchDB is exactly the same, just include libcouch-android as a library to your project, ICouchService.aidl are the functions you use to control CouchDB

How big is CouchDB? / CouchDB is too big for my app

Currently CouchDB is around 17MB uncompressed (about a 10MB download), There is a lot of work being done to reduce the size for both downloading and runtime memory footprint.

How do I use my own CouchApp

$ couchapp push --export > filename.json

Will produce a json file that can be loaded into Couch, the ExampleCouchApp.java will look for a json file in the assets folder for every database that is bootstrapped.

How do I access Geolocation etc from my CouchApp?

PhoneGap is a library that allows you to access native API’s via Javascript and is an excellent compliment to CouchDB on Android.

How do I publish my App?

Just follow the standard Android publishing procedure

CouchDB Reloads when I change orientation

Android by default will destroy your activity when your phone changes orientation, you can use

android:configChanges="keyboardHidden|orientation"

to avoid that, here is a working example.