Quick Start Guide

SQLDroid is a JDBC driver for the SQLite database on Android. The driver is built entirely around publish Android APIs and so, unlike the "hidden" JDBC driver that is part of Android, SQLDroid should support all future Android platforms.

This page assumes that you have some familiarity with using JDBC, the API to access SQL Databases from within Java. If you are not familiar with JDBC, please study a good JDBC tutorial before attempting to use SQLDroid on Android, for example the Oracle JDBC Basics.

In order to use the SQLDroid driver you will need to put the SQLDroid Jar in the "libs" directory of your Android project. [There must be an easy way to do this from, say Eclipse]

There are two fundamental pieces of information you need to use any JDBC driver.

The first is the Driver class name. For SQLDroid this is:

"org.sqldroid.SQLDroidDriver"

The second is the URL. SQLDroid accepts two. The first is the SQLDroid URL:

"jdbc:sqldroid:[databasefile]"

for compatibility with non-Android driver it also accepts:

"jdbc:sqlite:[databasefile]"

databasefile refers to a file on the Android file system. SQLDroid will always open databases as read/write and so the databasefile need to be in a location on the file system that you can read and write. If the file doesn't exist SQLDroid will create it, so you also need that permission.

The easiest place to put this file is in the package that contains your app. So if you are creating an addressbook Android app in "com.example.myandroid" then your url might be:

"jdbc:sqldroid:/data/data/com.example.myandroid/addressbook.db"

you are free to choose any file name as long as the path has read/write/create permissions.

The path to the app can be replaced by the Activity method getDataPath().

So from the main activity the url may be created as:

"jdbc:sqldroid:" + getDataPath() + "/addressbook.db"

The SQLite file stored on android is in the standard SQLite3 format so data files can be shared with other systems. One convenient way to do this, and to share data between different apps on the same Android device is to write the database file to the SDCard. This insecure in that any application on the Android device could read the data, or the SDCard could be removed and read by anyone with a PC or Android device. So, don't put any data that may be considered confidential in any way in a database on the SDCard.

In order to write to the SDCard you need the line:

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

in the Android Manifest file.

The URL to access data on the SDCard is of the form:

"jdbc:sqldroid:/sdcard/freelyreadableandtotallyinsecure.db"

With the Driver and URL the SQLDroid driver can be used like any other JDBC driver.

On Android, it can be difficult to debug code because it is not always easy to look at the database. There are a couple of tricks that can help. The first is to copy the database off the device and use sqlite3 on a desktop platform to look at the file. Some Android devices also have sqlite3 installed and so you can examine the database directly on the device. Some information on this can be found at this page.

While SQLDroid does not support the complete JDBC interfaces (few JDBC drivers do) it should be complete enough for most applications. In particular, SQLDroid provide support for BLOBS. BLOBS are very useful on Android for storing images, particular for applications using the Camera.