public abstract class

SQLiteOpenHelper

extends Object
java.lang.Object
   ↳ android.database.sqlite.SQLiteOpenHelper

Class Overview

A helper class to manage database creation and version management.

You create a subclass implementing onCreate(SQLiteDatabase), onUpgrade(SQLiteDatabase, int, int) and optionally onOpen(SQLiteDatabase), and this class takes care of opening the database if it exists, creating it if it does not, and upgrading it as necessary. Transactions are used to make sure the database is always in a sensible state.

This class makes it easy for ContentProvider implementations to defer opening and upgrading the database until first use, to avoid blocking application startup with long-running database upgrades.

For an example, see the NotePadProvider class in the NotePad sample application, in the samples/ directory of the SDK.

Note: this class assumes monotonically increasing version numbers for upgrades. Also, there is no concept of a database downgrade; installing a new version of your app which uses a lower version number than a previously-installed version will result in undefined behavior.

Summary

Public Constructors
SQLiteOpenHelper(Context context, String name, SQLiteDatabase.CursorFactory factory, int version)
Create a helper object to create, open, and/or manage a database.
Public Methods
synchronized void close()
Close any open database object.
synchronized SQLiteDatabase getReadableDatabase()
Create and/or open a database.
synchronized SQLiteDatabase getWritableDatabase()
Create and/or open a database that will be used for reading and writing.
abstract void onCreate(SQLiteDatabase db)
Called when the database is created for the first time.
void onOpen(SQLiteDatabase db)
Called when the database has been opened.
abstract void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion)
Called when the database needs to be upgraded.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public SQLiteOpenHelper (Context context, String name, SQLiteDatabase.CursorFactory factory, int version)

Since: API Level 1

Create a helper object to create, open, and/or manage a database. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase() or getReadableDatabase() is called.

Parameters
context to use to open or create the database
name of the database file, or null for an in-memory database
factory to use for creating cursor objects, or null for the default
version number of the database (starting at 1); if the database is older, onUpgrade(SQLiteDatabase, int, int) will be used to upgrade the database

Public Methods

public synchronized void close ()

Since: API Level 1

Close any open database object.

public synchronized SQLiteDatabase getReadableDatabase ()

Since: API Level 1

Create and/or open a database. This will be the same object returned by getWritableDatabase() unless some problem, such as a full disk, requires the database to be opened read-only. In that case, a read-only database object will be returned. If the problem is fixed, a future call to getWritableDatabase() may succeed, in which case the read-only database object will be closed and the read/write object will be returned in the future.

Like getWritableDatabase(), this method may take a long time to return, so you should not call it from the application main thread, including from ContentProvider.onCreate().

Returns
Throws
SQLiteException if the database cannot be opened

public synchronized SQLiteDatabase getWritableDatabase ()

Since: API Level 1

Create and/or open a database that will be used for reading and writing. The first time this is called, the database will be opened and onCreate(SQLiteDatabase), onUpgrade(SQLiteDatabase, int, int) and/or onOpen(SQLiteDatabase) will be called.

Once opened successfully, the database is cached, so you can call this method every time you need to write to the database. (Make sure to call close() when you no longer need the database.) Errors such as bad permissions or a full disk may cause this method to fail, but future attempts may succeed if the problem is fixed.

Database upgrade may take a long time, you should not call this method from the application main thread, including from ContentProvider.onCreate().

Returns
  • a read/write database object valid until close() is called
Throws
SQLiteException if the database cannot be opened for writing

public abstract void onCreate (SQLiteDatabase db)

Since: API Level 1

Called when the database is created for the first time. This is where the creation of tables and the initial population of the tables should happen.

Parameters
db The database.

public void onOpen (SQLiteDatabase db)

Since: API Level 1

Called when the database has been opened. The implementation should check isReadOnly() before updating the database.

Parameters
db The database.

public abstract void onUpgrade (SQLiteDatabase db, int oldVersion, int newVersion)

Since: API Level 1

Called when the database needs to be upgraded. The implementation should use this method to drop tables, add tables, or do anything else it needs to upgrade to the new schema version.

The SQLite ALTER TABLE documentation can be found here. If you add new columns you can use ALTER TABLE to insert them into a live table. If you rename or remove columns you can use ALTER TABLE to rename the old table, then create the new table and then populate the new table with the contents of the old table.

Parameters
db The database.
oldVersion The old database version.
newVersion The new database version.