Android APIs
public class

DatabaseUtils

extends Object
java.lang.Object
   ↳ android.database.DatabaseUtils

Class Overview

Static utility methods for dealing with databases and Cursors.

Summary

Nested Classes
class DatabaseUtils.InsertHelper This class was deprecated in API level 17. Use SQLiteStatement instead.  
Constants
int STATEMENT_ABORT One of the values returned by getSqlStatementType(String).
int STATEMENT_ATTACH One of the values returned by getSqlStatementType(String).
int STATEMENT_BEGIN One of the values returned by getSqlStatementType(String).
int STATEMENT_COMMIT One of the values returned by getSqlStatementType(String).
int STATEMENT_DDL One of the values returned by getSqlStatementType(String).
int STATEMENT_OTHER One of the values returned by getSqlStatementType(String).
int STATEMENT_PRAGMA One of the values returned by getSqlStatementType(String).
int STATEMENT_SELECT One of the values returned by getSqlStatementType(String).
int STATEMENT_UNPREPARED One of the values returned by getSqlStatementType(String).
int STATEMENT_UPDATE One of the values returned by getSqlStatementType(String).
Public Constructors
DatabaseUtils()
Public Methods
static void appendEscapedSQLString(StringBuilder sb, String sqlString)
Appends an SQL string to the given StringBuilder, including the opening and closing single quotes.
static String[] appendSelectionArgs(String[] originalValues, String[] newValues)
Appends one set of selection args to another.
final static void appendValueToSql(StringBuilder sql, Object value)
Appends an Object to an SQL string with the proper escaping, etc.
static void bindObjectToProgram(SQLiteProgram prog, int index, Object value)
Binds the given Object to the given SQLiteProgram using the proper typing.
static ParcelFileDescriptor blobFileDescriptorForQuery(SQLiteStatement prog, String[] selectionArgs)
Utility method to run the pre-compiled query and return the blob value in the first column of the first row.
static ParcelFileDescriptor blobFileDescriptorForQuery(SQLiteDatabase db, String query, String[] selectionArgs)
Utility method to run the query on the db and return the blob value in the first column of the first row.
static String concatenateWhere(String a, String b)
Concatenates two SQL WHERE clauses, handling empty or null values.
static void createDbFromSqlStatements(Context context, String dbName, int dbVersion, String sqlStatements)
Creates a db and populates it with the sql statements in sqlStatements.
static void cursorDoubleToContentValues(Cursor cursor, String field, ContentValues values, String key)
Reads a Double out of a field in a Cursor and writes it to a Map.
static void cursorDoubleToContentValuesIfPresent(Cursor cursor, ContentValues values, String column)
Reads a Double out of a column in a Cursor and writes it to a ContentValues.
static void cursorDoubleToCursorValues(Cursor cursor, String field, ContentValues values)
Reads a Double out of a field in a Cursor and writes it to a Map.
static void cursorFloatToContentValuesIfPresent(Cursor cursor, ContentValues values, String column)
Reads a Float out of a column in a Cursor and writes it to a ContentValues.
static void cursorIntToContentValues(Cursor cursor, String field, ContentValues values, String key)
Reads a Integer out of a field in a Cursor and writes it to a Map.
static void cursorIntToContentValues(Cursor cursor, String field, ContentValues values)
Reads an Integer out of a field in a Cursor and writes it to a Map.
static void cursorIntToContentValuesIfPresent(Cursor cursor, ContentValues values, String column)
Reads a Integer out of a column in a Cursor and writes it to a ContentValues.
static void cursorLongToContentValues(Cursor cursor, String field, ContentValues values, String key)
Reads a Long out of a field in a Cursor and writes it to a Map.
static void cursorLongToContentValues(Cursor cursor, String field, ContentValues values)
Reads a Long out of a field in a Cursor and writes it to a Map.
static void cursorLongToContentValuesIfPresent(Cursor cursor, ContentValues values, String column)
Reads a Long out of a column in a Cursor and writes it to a ContentValues.
static void cursorRowToContentValues(Cursor cursor, ContentValues values)
Read the entire contents of a cursor row and store them in a ContentValues.
static void cursorShortToContentValuesIfPresent(Cursor cursor, ContentValues values, String column)
Reads a Short out of a column in a Cursor and writes it to a ContentValues.
static void cursorStringToContentValues(Cursor cursor, String field, ContentValues values, String key)
Reads a String out of a field in a Cursor and writes it to a Map.
static void cursorStringToContentValues(Cursor cursor, String field, ContentValues values)
Reads a String out of a field in a Cursor and writes it to a Map.
static void cursorStringToContentValuesIfPresent(Cursor cursor, ContentValues values, String column)
Reads a String out of a column in a Cursor and writes it to a ContentValues.
static void cursorStringToInsertHelper(Cursor cursor, String field, DatabaseUtils.InsertHelper inserter, int index)
Reads a String out of a field in a Cursor and writes it to an InsertHelper.
static void dumpCurrentRow(Cursor cursor, PrintStream stream)
Prints the contents of a Cursor's current row to a PrintSteam.
static void dumpCurrentRow(Cursor cursor, StringBuilder sb)
Prints the contents of a Cursor's current row to a StringBuilder.
static void dumpCurrentRow(Cursor cursor)
Prints the contents of a Cursor's current row to System.out.
static String dumpCurrentRowToString(Cursor cursor)
Dump the contents of a Cursor's current row to a String.
static void dumpCursor(Cursor cursor, PrintStream stream)
Prints the contents of a Cursor to a PrintSteam.
static void dumpCursor(Cursor cursor, StringBuilder sb)
Prints the contents of a Cursor to a StringBuilder.
static void dumpCursor(Cursor cursor)
Prints the contents of a Cursor to System.out.
static String dumpCursorToString(Cursor cursor)
Prints the contents of a Cursor to a String.
static String getCollationKey(String name)
return the collation key
static String getHexCollationKey(String name)
return the collation key in hex format
static int getSqlStatementType(String sql)
Returns one of the following which represent the type of the given SQL statement.
static long longForQuery(SQLiteDatabase db, String query, String[] selectionArgs)
Utility method to run the query on the db and return the value in the first column of the first row.
static long longForQuery(SQLiteStatement prog, String[] selectionArgs)
Utility method to run the pre-compiled query and return the value in the first column of the first row.
static long queryNumEntries(SQLiteDatabase db, String table)
Query the table for the number of rows in the table.
static long queryNumEntries(SQLiteDatabase db, String table, String selection)
Query the table for the number of rows in the table.
static long queryNumEntries(SQLiteDatabase db, String table, String selection, String[] selectionArgs)
Query the table for the number of rows in the table.
final static void readExceptionFromParcel(Parcel reply)
Special function for reading an exception result from the header of a parcel, to be used after receiving the result of a transaction.
static void readExceptionWithFileNotFoundExceptionFromParcel(Parcel reply)
static void readExceptionWithOperationApplicationExceptionFromParcel(Parcel reply)
static String sqlEscapeString(String value)
SQL-escape a string.
static String stringForQuery(SQLiteDatabase db, String query, String[] selectionArgs)
Utility method to run the query on the db and return the value in the first column of the first row.
static String stringForQuery(SQLiteStatement prog, String[] selectionArgs)
Utility method to run the pre-compiled query and return the value in the first column of the first row.
final static void writeExceptionToParcel(Parcel reply, Exception e)
Special function for writing an exception result at the header of a parcel, to be used when returning an exception from a transaction.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int STATEMENT_ABORT

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 6 (0x00000006)

public static final int STATEMENT_ATTACH

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 3 (0x00000003)

public static final int STATEMENT_BEGIN

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 4 (0x00000004)

public static final int STATEMENT_COMMIT

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 5 (0x00000005)

public static final int STATEMENT_DDL

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 8 (0x00000008)

public static final int STATEMENT_OTHER

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 99 (0x00000063)

public static final int STATEMENT_PRAGMA

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 7 (0x00000007)

public static final int STATEMENT_SELECT

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 1 (0x00000001)

public static final int STATEMENT_UNPREPARED

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 9 (0x00000009)

public static final int STATEMENT_UPDATE

Added in API level 11

One of the values returned by getSqlStatementType(String).

Constant Value: 2 (0x00000002)

Public Constructors

public DatabaseUtils ()

Added in API level 1

Public Methods

public static void appendEscapedSQLString (StringBuilder sb, String sqlString)

Added in API level 1

Appends an SQL string to the given StringBuilder, including the opening and closing single quotes. Any single quotes internal to sqlString will be escaped. This method is deprecated because we want to encourage everyone to use the "?" binding form. However, when implementing a ContentProvider, one may want to add WHERE clauses that were not provided by the caller. Since "?" is a positional form, using it in this case could break the caller because the indexes would be shifted to accomodate the ContentProvider's internal bindings. In that case, it may be necessary to construct a WHERE clause manually. This method is useful for those cases.

Parameters
sb StringBuilder: the StringBuilder that the SQL string will be appended to
sqlString String: the raw string to be appended, which may contain single quotes

public static String[] appendSelectionArgs (String[] originalValues, String[] newValues)

Added in API level 11

Appends one set of selection args to another. This is useful when adding a selection argument to a user provided set.

Parameters
originalValues String
newValues String
Returns
String[]

public static final void appendValueToSql (StringBuilder sql, Object value)

Added in API level 1

Appends an Object to an SQL string with the proper escaping, etc.

Parameters
sql StringBuilder
value Object

public static void bindObjectToProgram (SQLiteProgram prog, int index, Object value)

Added in API level 1

Binds the given Object to the given SQLiteProgram using the proper typing. For example, bind numbers as longs/doubles, and everything else as a string by call toString() on it.

Parameters
prog SQLiteProgram: the program to bind the object to
index int: the 1-based index to bind at
value Object: the value to bind

public static ParcelFileDescriptor blobFileDescriptorForQuery (SQLiteStatement prog, String[] selectionArgs)

Added in API level 11

Utility method to run the pre-compiled query and return the blob value in the first column of the first row.

Parameters
prog SQLiteStatement
selectionArgs String
Returns
ParcelFileDescriptor A read-only file descriptor for a copy of the blob value.

public static ParcelFileDescriptor blobFileDescriptorForQuery (SQLiteDatabase db, String query, String[] selectionArgs)

Added in API level 11

Utility method to run the query on the db and return the blob value in the first column of the first row.

Parameters
db SQLiteDatabase
query String
selectionArgs String
Returns
ParcelFileDescriptor A read-only file descriptor for a copy of the blob value.

public static String concatenateWhere (String a, String b)

Added in API level 11

Concatenates two SQL WHERE clauses, handling empty or null values.

Parameters
a String
b String
Returns
String

public static void createDbFromSqlStatements (Context context, String dbName, int dbVersion, String sqlStatements)

Added in API level 1

Creates a db and populates it with the sql statements in sqlStatements.

Parameters
context Context: the context to use to create the db
dbName String: the name of the db to create
dbVersion int: the version to set on the db
sqlStatements String: the statements to use to populate the db. This should be a single string of the form returned by sqlite3's .dump command (statements separated by semicolons)

public static void cursorDoubleToContentValues (Cursor cursor, String field, ContentValues values, String key)

Added in API level 1

Reads a Double out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The REAL field to read
values ContentValues: The ContentValues to put the value into
key String: The key to store the value with in the map

public static void cursorDoubleToContentValuesIfPresent (Cursor cursor, ContentValues values, String column)

Added in API level 8

Reads a Double out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.

Parameters
cursor Cursor: The cursor to read from
values ContentValues: The ContentValues to put the value into
column String: The column to read

public static void cursorDoubleToCursorValues (Cursor cursor, String field, ContentValues values)

Added in API level 1

Reads a Double out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The REAL field to read
values ContentValues: The ContentValues to put the value into

public static void cursorFloatToContentValuesIfPresent (Cursor cursor, ContentValues values, String column)

Added in API level 8

Reads a Float out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.

Parameters
cursor Cursor: The cursor to read from
values ContentValues: The ContentValues to put the value into
column String: The column to read

public static void cursorIntToContentValues (Cursor cursor, String field, ContentValues values, String key)

Added in API level 1

Reads a Integer out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The INTEGER field to read
values ContentValues: The ContentValues to put the value into, with the field as the key
key String: The key to store the value with in the map

public static void cursorIntToContentValues (Cursor cursor, String field, ContentValues values)

Added in API level 1

Reads an Integer out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The INTEGER field to read
values ContentValues: The ContentValues to put the value into, with the field as the key

public static void cursorIntToContentValuesIfPresent (Cursor cursor, ContentValues values, String column)

Added in API level 8

Reads a Integer out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.

Parameters
cursor Cursor: The cursor to read from
values ContentValues: The ContentValues to put the value into
column String: The column to read

public static void cursorLongToContentValues (Cursor cursor, String field, ContentValues values, String key)

Added in API level 1

Reads a Long out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The INTEGER field to read
values ContentValues: The ContentValues to put the value into
key String: The key to store the value with in the map

public static void cursorLongToContentValues (Cursor cursor, String field, ContentValues values)

Added in API level 1

Reads a Long out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The INTEGER field to read
values ContentValues: The ContentValues to put the value into, with the field as the key

public static void cursorLongToContentValuesIfPresent (Cursor cursor, ContentValues values, String column)

Added in API level 8

Reads a Long out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.

Parameters
cursor Cursor: The cursor to read from
values ContentValues: The ContentValues to put the value into
column String: The column to read

public static void cursorRowToContentValues (Cursor cursor, ContentValues values)

Added in API level 1

Read the entire contents of a cursor row and store them in a ContentValues.

Parameters
cursor Cursor: the cursor to read from.
values ContentValues: the ContentValues to put the row into.

public static void cursorShortToContentValuesIfPresent (Cursor cursor, ContentValues values, String column)

Added in API level 8

Reads a Short out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.

Parameters
cursor Cursor: The cursor to read from
values ContentValues: The ContentValues to put the value into
column String: The column to read

public static void cursorStringToContentValues (Cursor cursor, String field, ContentValues values, String key)

Added in API level 1

Reads a String out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The TEXT field to read
values ContentValues: The ContentValues to put the value into, with the field as the key
key String: The key to store the value with in the map

public static void cursorStringToContentValues (Cursor cursor, String field, ContentValues values)

Added in API level 1

Reads a String out of a field in a Cursor and writes it to a Map.

Parameters
cursor Cursor: The cursor to read from
field String: The TEXT field to read
values ContentValues: The ContentValues to put the value into, with the field as the key

public static void cursorStringToContentValuesIfPresent (Cursor cursor, ContentValues values, String column)

Added in API level 8

Reads a String out of a column in a Cursor and writes it to a ContentValues. Adds nothing to the ContentValues if the column isn't present or if its value is null.

Parameters
cursor Cursor: The cursor to read from
values ContentValues: The ContentValues to put the value into
column String: The column to read

public static void cursorStringToInsertHelper (Cursor cursor, String field, DatabaseUtils.InsertHelper inserter, int index)

Added in API level 1

Reads a String out of a field in a Cursor and writes it to an InsertHelper.

Parameters
cursor Cursor: The cursor to read from
field String: The TEXT field to read
inserter DatabaseUtils.InsertHelper: The InsertHelper to bind into
index int: the index of the bind entry in the InsertHelper

public static void dumpCurrentRow (Cursor cursor, PrintStream stream)

Added in API level 1

Prints the contents of a Cursor's current row to a PrintSteam.

Parameters
cursor Cursor: the cursor to print
stream PrintStream: the stream to print to

public static void dumpCurrentRow (Cursor cursor, StringBuilder sb)

Added in API level 1

Prints the contents of a Cursor's current row to a StringBuilder.

Parameters
cursor Cursor: the cursor to print
sb StringBuilder: the StringBuilder to print to

public static void dumpCurrentRow (Cursor cursor)

Added in API level 1

Prints the contents of a Cursor's current row to System.out.

Parameters
cursor Cursor: the cursor to print from

public static String dumpCurrentRowToString (Cursor cursor)

Added in API level 1

Dump the contents of a Cursor's current row to a String.

Parameters
cursor Cursor: the cursor to print
Returns
String a String that contains the dumped cursor row

public static void dumpCursor (Cursor cursor, PrintStream stream)

Added in API level 1

Prints the contents of a Cursor to a PrintSteam. The position is restored after printing.

Parameters
cursor Cursor: the cursor to print
stream PrintStream: the stream to print to

public static void dumpCursor (Cursor cursor, StringBuilder sb)

Added in API level 1

Prints the contents of a Cursor to a StringBuilder. The position is restored after printing.

Parameters
cursor Cursor: the cursor to print
sb StringBuilder: the StringBuilder to print to

public static void dumpCursor (Cursor cursor)

Added in API level 1

Prints the contents of a Cursor to System.out. The position is restored after printing.

Parameters
cursor Cursor: the cursor to print

public static String dumpCursorToString (Cursor cursor)

Added in API level 1

Prints the contents of a Cursor to a String. The position is restored after printing.

Parameters
cursor Cursor: the cursor to print
Returns
String a String that contains the dumped cursor

public static String getCollationKey (String name)

Added in API level 1

return the collation key

Returns
String the collation key

public static String getHexCollationKey (String name)

Added in API level 1

return the collation key in hex format

Returns
String the collation key in hex format

public static int getSqlStatementType (String sql)

Added in API level 11

Returns one of the following which represent the type of the given SQL statement.

  1. STATEMENT_SELECT
  2. STATEMENT_UPDATE
  3. STATEMENT_ATTACH
  4. STATEMENT_BEGIN
  5. STATEMENT_COMMIT
  6. STATEMENT_ABORT
  7. STATEMENT_OTHER

Parameters
sql String: the SQL statement whose type is returned by this method
Returns
int one of the values listed above

public static long longForQuery (SQLiteDatabase db, String query, String[] selectionArgs)

Added in API level 1

Utility method to run the query on the db and return the value in the first column of the first row.

Parameters
db SQLiteDatabase
query String
selectionArgs String
Returns
long

public static long longForQuery (SQLiteStatement prog, String[] selectionArgs)

Added in API level 1

Utility method to run the pre-compiled query and return the value in the first column of the first row.

Parameters
prog SQLiteStatement
selectionArgs String
Returns
long

public static long queryNumEntries (SQLiteDatabase db, String table)

Added in API level 1

Query the table for the number of rows in the table.

Parameters
db SQLiteDatabase: the database the table is in
table String: the name of the table to query
Returns
long the number of rows in the table

public static long queryNumEntries (SQLiteDatabase db, String table, String selection)

Added in API level 11

Query the table for the number of rows in the table.

Parameters
db SQLiteDatabase: the database the table is in
table String: the name of the table to query
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will count all rows for the given table
Returns
long the number of rows in the table filtered by the selection

public static long queryNumEntries (SQLiteDatabase db, String table, String selection, String[] selectionArgs)

Added in API level 11

Query the table for the number of rows in the table.

Parameters
db SQLiteDatabase: the database the table is in
table String: the name of the table to query
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will count all rows for the given table
selectionArgs String: You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.
Returns
long the number of rows in the table filtered by the selection

public static final void readExceptionFromParcel (Parcel reply)

Added in API level 1

Special function for reading an exception result from the header of a parcel, to be used after receiving the result of a transaction. This will throw the exception for you if it had been written to the Parcel, otherwise return and let you read the normal result data from the Parcel.

Parameters
reply Parcel: Parcel to read from

public static void readExceptionWithFileNotFoundExceptionFromParcel (Parcel reply)

Added in API level 1

Parameters
reply Parcel
Throws
FileNotFoundException

public static void readExceptionWithOperationApplicationExceptionFromParcel (Parcel reply)

Added in API level 5

Parameters
reply Parcel
Throws
OperationApplicationException

public static String sqlEscapeString (String value)

Added in API level 1

SQL-escape a string.

Parameters
value String
Returns
String

public static String stringForQuery (SQLiteDatabase db, String query, String[] selectionArgs)

Added in API level 1

Utility method to run the query on the db and return the value in the first column of the first row.

Parameters
db SQLiteDatabase
query String
selectionArgs String
Returns
String

public static String stringForQuery (SQLiteStatement prog, String[] selectionArgs)

Added in API level 1

Utility method to run the pre-compiled query and return the value in the first column of the first row.

Parameters
prog SQLiteStatement
selectionArgs String
Returns
String

public static final void writeExceptionToParcel (Parcel reply, Exception e)

Added in API level 1

Special function for writing an exception result at the header of a parcel, to be used when returning an exception from a transaction. exception will be re-thrown by the function in another process

Parameters
reply Parcel: Parcel to write to
e Exception: The Exception to be written.