added in version 1.1.0
belongs to Maven artifact android.arch.persistence:db:1.1.0-beta2

Summary: Methods | Inherited Methods

SupportSQLiteDatabase

The android.arch Architecture Components packages are no longer maintained. They have been superseded by the corresponding androidx.* packages. See androidx.sqlite.db.SupportSQLiteDatabase instead.

public interface SupportSQLiteDatabase
implements Closeable

android.arch.persistence.db.SupportSQLiteDatabase

---

A database abstraction which removes the framework dependency and allows swapping underlying sql versions. It mimics the behavior of SQLiteDatabase

Summary

Public methods
abstract void	beginTransaction() Begins a transaction in EXCLUSIVE mode.
abstract void	beginTransactionNonExclusive() Begins a transaction in IMMEDIATE mode.
abstract void	beginTransactionWithListener(SQLiteTransactionListener transactionListener) Begins a transaction in EXCLUSIVE mode.
abstract void	beginTransactionWithListenerNonExclusive(SQLiteTransactionListener transactionListener) Begins a transaction in IMMEDIATE mode.
abstract SupportSQLiteStatement	compileStatement(String sql) Compiles the given SQL statement.
abstract int	delete(String table, String whereClause, Object[] whereArgs) Convenience method for deleting rows in the database.
abstract void	disableWriteAheadLogging() This method disables the features enabled by enableWriteAheadLogging().
abstract boolean	enableWriteAheadLogging() This method enables parallel execution of queries from multiple threads on the same database.
abstract void	endTransaction() End a transaction.
abstract void	execSQL(String sql, Object[] bindArgs) Execute a single SQL statement that does not return any data.
abstract void	execSQL(String sql) Execute a single SQL statement that does not return any data.
abstract List<Pair<String, String>>	getAttachedDbs() Returns list of full path names of all attached databases including the main database by executing 'pragma database_list' on the database.
abstract long	getMaximumSize() Returns the maximum size the database may grow to.
abstract long	getPageSize() Returns the current database page size, in bytes.
abstract String	getPath() Gets the path to the database file.
abstract int	getVersion() Gets the database version.
abstract boolean	inTransaction() Returns true if the current thread has a transaction pending.
abstract long	insert(String table, int conflictAlgorithm, ContentValues values) Convenience method for inserting a row into the database.
abstract boolean	isDatabaseIntegrityOk() Runs 'pragma integrity_check' on the given database (and all the attached databases) and returns true if the given database (and all its attached databases) pass integrity_check, false otherwise.
abstract boolean	isDbLockedByCurrentThread() Returns true if the current thread is holding an active connection to the database.
abstract boolean	isOpen() Returns true if the database is currently open.
abstract boolean	isReadOnly() Returns true if the database is opened as read only.
abstract boolean	isWriteAheadLoggingEnabled() Returns true if write-ahead logging has been enabled for this database.
abstract boolean	needUpgrade(int newVersion) Returns true if the new version code is greater than the current database version.
abstract Cursor	query(SupportSQLiteQuery query) Runs the given query on the database.
abstract Cursor	query(String query) Runs the given query on the database.
abstract Cursor	query(String query, Object[] bindArgs) Runs the given query on the database.
abstract Cursor	query(SupportSQLiteQuery query, CancellationSignal cancellationSignal) Runs the given query on the database.
abstract void	setForeignKeyConstraintsEnabled(boolean enable) Sets whether foreign key constraints are enabled for the database.
abstract void	setLocale(Locale locale) Sets the locale for this database.
abstract void	setMaxSqlCacheSize(int cacheSize) Sets the maximum size of the prepared-statement cache for this database.
abstract long	setMaximumSize(long numBytes) Sets the maximum size the database will grow to.
abstract void	setPageSize(long numBytes) Sets the database page size.
abstract void	setTransactionSuccessful() Marks the current transaction as successful.
abstract void	setVersion(int version) Sets the database version.
abstract int	update(String table, int conflictAlgorithm, ContentValues values, String whereClause, Object[] whereArgs) Convenience method for updating rows in the database.
abstract boolean	yieldIfContendedSafely(long sleepAfterYieldDelay) Temporarily end the transaction to let other threads run.
abstract boolean	yieldIfContendedSafely() Temporarily end the transaction to let other threads run.

Inherited methods
From interface java.io.Closeable abstract void close()
From interface java.lang.AutoCloseable abstract void close()

Public methods

beginTransaction

added in version 1.1.0

void beginTransaction ()

Begins a transaction in EXCLUSIVE mode.

Transactions can be nested. When the outer transaction is ended all of the work done in that transaction and all of the nested transactions will be committed or rolled back. The changes will be rolled back if any transaction is ended without being marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed.

Here is the standard idiom for transactions:

   db.beginTransaction();
   try {
     ...
     db.setTransactionSuccessful();
   } finally {
     db.endTransaction();
   }
 

beginTransactionNonExclusive

added in version 1.1.0

void beginTransactionNonExclusive ()

Begins a transaction in IMMEDIATE mode. Transactions can be nested. When the outer transaction is ended all of the work done in that transaction and all of the nested transactions will be committed or rolled back. The changes will be rolled back if any transaction is ended without being marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed.

Here is the standard idiom for transactions:

   db.beginTransactionNonExclusive();
   try {
     ...
     db.setTransactionSuccessful();
   } finally {
     db.endTransaction();
   }
 

beginTransactionWithListener

added in version 1.1.0

void beginTransactionWithListener (SQLiteTransactionListener transactionListener)

Begins a transaction in EXCLUSIVE mode.

Transactions can be nested. When the outer transaction is ended all of the work done in that transaction and all of the nested transactions will be committed or rolled back. The changes will be rolled back if any transaction is ended without being marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed.

Here is the standard idiom for transactions:

   db.beginTransactionWithListener(listener);
   try {
     ...
     db.setTransactionSuccessful();
   } finally {
     db.endTransaction();
   }
 

Parameters
transactionListener	SQLiteTransactionListener: listener that should be notified when the transaction begins, commits, or is rolled back, either explicitly or by a call to yieldIfContendedSafely().

beginTransactionWithListenerNonExclusive

added in version 1.1.0

void beginTransactionWithListenerNonExclusive (SQLiteTransactionListener transactionListener)

Begins a transaction in IMMEDIATE mode. Transactions can be nested. When the outer transaction is ended all of the work done in that transaction and all of the nested transactions will be committed or rolled back. The changes will be rolled back if any transaction is ended without being marked as clean (by calling setTransactionSuccessful). Otherwise they will be committed.

Here is the standard idiom for transactions:

   db.beginTransactionWithListenerNonExclusive(listener);
   try {
     ...
     db.setTransactionSuccessful();
   } finally {
     db.endTransaction();
   }
 

Parameters
transactionListener	SQLiteTransactionListener: listener that should be notified when the transaction begins, commits, or is rolled back, either explicitly or by a call to yieldIfContendedSafely().

compileStatement

added in version 1.1.0

SupportSQLiteStatement compileStatement (String sql)

Compiles the given SQL statement.

Parameters
sql	String: The sql query.

Returns
SupportSQLiteStatement	Compiled statement.

delete

added in version 1.1.0

int delete (String table, 
                String whereClause, 
                Object[] whereArgs)

Convenience method for deleting rows in the database.

Parameters
table	String: the table to delete from
whereClause	String: the optional WHERE clause to apply when deleting. Passing null will delete all rows.
whereArgs	Object: You may include ?s in the where clause, which will be replaced by the values from whereArgs. The values will be bound as Strings.

Returns
int	the number of rows affected if a whereClause is passed in, 0 otherwise. To remove all rows and get a count pass "1" as the whereClause.

disableWriteAheadLogging

added in version 1.1.0

void disableWriteAheadLogging ()

This method disables the features enabled by enableWriteAheadLogging().

Throws
IllegalStateException	if there are transactions in progress at the time this method is called. WAL mode can only be changed when there are no transactions in progress.

See also:

• enableWriteAheadLogging()

enableWriteAheadLogging

added in version 1.1.0

boolean enableWriteAheadLogging ()

This method enables parallel execution of queries from multiple threads on the same database. It does this by opening multiple connections to the database and using a different database connection for each query. The database journal mode is also changed to enable writes to proceed concurrently with reads.

When write-ahead logging is not enabled (the default), it is not possible for reads and writes to occur on the database at the same time. Before modifying the database, the writer implicitly acquires an exclusive lock on the database which prevents readers from accessing the database until the write is completed.

In contrast, when write-ahead logging is enabled (by calling this method), write operations occur in a separate log file which allows reads to proceed concurrently. While a write is in progress, readers on other threads will perceive the state of the database as it was before the write began. When the write completes, readers on other threads will then perceive the new state of the database.

It is a good idea to enable write-ahead logging whenever a database will be concurrently accessed and modified by multiple threads at the same time. However, write-ahead logging uses significantly more memory than ordinary journaling because there are multiple connections to the same database. So if a database will only be used by a single thread, or if optimizing concurrency is not very important, then write-ahead logging should be disabled.

After calling this method, execution of queries in parallel is enabled as long as the database remains open. To disable execution of queries in parallel, either call disableWriteAheadLogging() or close the database and reopen it.

The maximum number of connections used to execute queries in parallel is dependent upon the device memory and possibly other properties.

If a query is part of a transaction, then it is executed on the same database handle the transaction was begun.

Writers should use beginTransactionNonExclusive() or beginTransactionWithListenerNonExclusive(SQLiteTransactionListener) to start a transaction. Non-exclusive mode allows database file to be in readable by other threads executing queries.

If the database has any attached databases, then execution of queries in parallel is NOT possible. Likewise, write-ahead logging is not supported for read-only databases or memory databases. In such cases, enableWriteAheadLogging returns false.

The best way to enable write-ahead logging is to pass the ENABLE_WRITE_AHEAD_LOGGING flag to openDatabase(File, SQLiteDatabase.OpenParams). This is more efficient than calling

     SQLiteDatabase db = SQLiteDatabase.openDatabase("db_filename", cursorFactory,
             SQLiteDatabase.CREATE_IF_NECESSARY | SQLiteDatabase.ENABLE_WRITE_AHEAD_LOGGING,
             myDatabaseErrorHandler);
     db.enableWriteAheadLogging();
 

Another way to enable write-ahead logging is to call enableWriteAheadLogging after opening the database.

     SQLiteDatabase db = SQLiteDatabase.openDatabase("db_filename", cursorFactory,
             SQLiteDatabase.CREATE_IF_NECESSARY, myDatabaseErrorHandler);
     db.enableWriteAheadLogging();
 

See also SQLite Write-Ahead Logging for more details about how write-ahead logging works.

Returns
boolean	True if write-ahead logging is enabled.

Throws
IllegalStateException	if there are transactions in progress at the time this method is called. WAL mode can only be changed when there are no transactions in progress.

See also:

• ENABLE_WRITE_AHEAD_LOGGING
• disableWriteAheadLogging()

endTransaction

added in version 1.1.0

void endTransaction ()

End a transaction. See beginTransaction for notes about how to use this and when transactions are committed and rolled back.

execSQL

added in version 1.1.0

void execSQL (String sql, 
                Object[] bindArgs)

Execute a single SQL statement that does not return any data.

When using enableWriteAheadLogging(), journal_mode is automatically managed by this class. So, do not set journal_mode using "PRAGMA journal_mode'" statement if your app is using enableWriteAheadLogging()

Parameters
sql	String: the SQL statement to be executed. Multiple statements separated by semicolons are not supported.
bindArgs	Object: only byte[], String, Long and Double are supported in selectionArgs.

Throws
SQLException	if the SQL string is invalid

See also:

• query(SupportSQLiteQuery)

execSQL

added in version 1.1.0

void execSQL (String sql)

Execute a single SQL statement that does not return any data.

When using enableWriteAheadLogging(), journal_mode is automatically managed by this class. So, do not set journal_mode using "PRAGMA journal_mode'" statement if your app is using enableWriteAheadLogging()

Parameters
sql	String: the SQL statement to be executed. Multiple statements separated by semicolons are not supported.

Throws
SQLException	if the SQL string is invalid

See also:

• query(SupportSQLiteQuery)

getAttachedDbs

added in version 1.1.0

List<Pair<String, String>> getAttachedDbs ()

Returns list of full path names of all attached databases including the main database by executing 'pragma database_list' on the database.

Returns
List<Pair<String, String>>	ArrayList of pairs of (database name, database file path) or null if the database is not open.

getMaximumSize

added in version 1.1.0

long getMaximumSize ()

Returns the maximum size the database may grow to.

Returns
long	the new maximum database size

getPageSize

added in version 1.1.0

long getPageSize ()

Returns the current database page size, in bytes.

Returns
long	the database page size, in bytes

getPath

added in version 1.1.0

String getPath ()

Gets the path to the database file.

Returns
String	The path to the database file.

getVersion

added in version 1.1.0

int getVersion ()

Gets the database version.

Returns
int	the database version

inTransaction

added in version 1.1.0

boolean inTransaction ()

Returns true if the current thread has a transaction pending.

Returns
boolean	True if the current thread is in a transaction.

insert

added in version 1.1.0

long insert (String table, 
                int conflictAlgorithm, 
                ContentValues values)

Convenience method for inserting a row into the database.

Parameters
table	String: the table to insert the row into
conflictAlgorithm	int: for insert conflict resolver. One of CONFLICT_NONE, CONFLICT_ROLLBACK, CONFLICT_ABORT, CONFLICT_FAIL, CONFLICT_IGNORE, CONFLICT_REPLACE.
values	ContentValues: this map contains the initial column values for the row. The keys should be the column names and the values the column values

Returns
long	the row ID of the newly inserted row, or -1 if an error occurred

Throws
SQLException	If the insert fails

isDatabaseIntegrityOk

added in version 1.1.0

boolean isDatabaseIntegrityOk ()

Runs 'pragma integrity_check' on the given database (and all the attached databases) and returns true if the given database (and all its attached databases) pass integrity_check, false otherwise.

If the result is false, then this method logs the errors reported by the integrity_check command execution.

Note that 'pragma integrity_check' on a database can take a long time.

Returns
boolean	true if the given database (and all its attached databases) pass integrity_check, false otherwise.

isDbLockedByCurrentThread

added in version 1.1.0

boolean isDbLockedByCurrentThread ()

Returns true if the current thread is holding an active connection to the database.

The name of this method comes from a time when having an active connection to the database meant that the thread was holding an actual lock on the database. Nowadays, there is no longer a true "database lock" although threads may block if they cannot acquire a database connection to perform a particular operation.

Returns
boolean	True if the current thread is holding an active connection to the database.

isOpen

added in version 1.1.0

boolean isOpen ()

Returns true if the database is currently open.

Returns
boolean	True if the database is currently open (has not been closed).

isReadOnly

added in version 1.1.0

boolean isReadOnly ()

Returns true if the database is opened as read only.

Returns
boolean	True if database is opened as read only.

isWriteAheadLoggingEnabled

added in version 1.1.0

boolean isWriteAheadLoggingEnabled ()

Returns true if write-ahead logging has been enabled for this database.

Returns
boolean	True if write-ahead logging has been enabled for this database.

See also:

• enableWriteAheadLogging()
• ENABLE_WRITE_AHEAD_LOGGING

needUpgrade

added in version 1.1.0

boolean needUpgrade (int newVersion)

Returns true if the new version code is greater than the current database version.

Parameters
newVersion	int: The new version code.

Returns
boolean	True if the new version code is greater than the current database version.

query

added in version 1.1.0

Cursor query (SupportSQLiteQuery query)

Runs the given query on the database.

This class allows using type safe sql program bindings while running queries.

Parameters
query	SupportSQLiteQuery: The SQL query that includes the query and can bind into a given compiled program.

Returns
Cursor	A Cursor object, which is positioned before the first entry. Note that Cursors are not synchronized, see the documentation for more details.

See also:

• SimpleSQLiteQuery

query

added in version 1.1.0

Cursor query (String query)

Runs the given query on the database. If you would like to have typed bind arguments, use query(SupportSQLiteQuery).

Parameters
query	String: The SQL query that includes the query and can bind into a given compiled program.

Returns
Cursor	A Cursor object, which is positioned before the first entry. Note that Cursors are not synchronized, see the documentation for more details.

See also:

• query(SupportSQLiteQuery)

query

added in version 1.1.0

Cursor query (String query, 
                Object[] bindArgs)

Runs the given query on the database. If you would like to have bind arguments, use query(SupportSQLiteQuery).

Parameters
query	String: The SQL query that includes the query and can bind into a given compiled program.
bindArgs	Object: The query arguments to bind.

Returns
Cursor	A Cursor object, which is positioned before the first entry. Note that Cursors are not synchronized, see the documentation for more details.

See also:

• query(SupportSQLiteQuery)

query

added in version 1.1.0

Cursor query (SupportSQLiteQuery query, 
                CancellationSignal cancellationSignal)

Runs the given query on the database.

This class allows using type safe sql program bindings while running queries.

Parameters
query	SupportSQLiteQuery: The SQL query that includes the query and can bind into a given compiled program.
cancellationSignal	CancellationSignal: A signal to cancel the operation in progress, or null if none. If the operation is canceled, then OperationCanceledException will be thrown when the query is executed.

Returns
Cursor	A Cursor object, which is positioned before the first entry. Note that Cursors are not synchronized, see the documentation for more details.

setForeignKeyConstraintsEnabled

added in version 1.1.0

void setForeignKeyConstraintsEnabled (boolean enable)

Sets whether foreign key constraints are enabled for the database.

By default, foreign key constraints are not enforced by the database. This method allows an application to enable foreign key constraints. It must be called each time the database is opened to ensure that foreign key constraints are enabled for the session.

A good time to call this method is right after calling #openOrCreateDatabase or in the onConfigure(SupportSQLiteDatabase) callback.

When foreign key constraints are disabled, the database does not check whether changes to the database will violate foreign key constraints. Likewise, when foreign key constraints are disabled, the database will not execute cascade delete or update triggers. As a result, it is possible for the database state to become inconsistent. To perform a database integrity check, call isDatabaseIntegrityOk().

This method must not be called while a transaction is in progress.

See also SQLite Foreign Key Constraints for more details about foreign key constraint support.

Parameters
enable	boolean: True to enable foreign key constraints, false to disable them.

Throws
IllegalStateException	if the are transactions is in progress when this method is called.

setLocale

added in version 1.1.0

void setLocale (Locale locale)

Sets the locale for this database. Does nothing if this database has the NO_LOCALIZED_COLLATORS flag set or was opened read only.

Parameters
locale	Locale: The new locale.

Throws
SQLException	if the locale could not be set. The most common reason for this is that there is no collator available for the locale you requested. In this case the database remains unchanged.

setMaxSqlCacheSize

added in version 1.1.0

void setMaxSqlCacheSize (int cacheSize)

Sets the maximum size of the prepared-statement cache for this database. (size of the cache = number of compiled-sql-statements stored in the cache).

Maximum cache size can ONLY be increased from its current size (default = 10). If this method is called with smaller size than the current maximum value, then IllegalStateException is thrown.

This method is thread-safe.

Parameters
cacheSize	int: the size of the cache. can be (0 to MAX_SQL_CACHE_SIZE)

Throws
IllegalStateException	if input cacheSize gt; MAX_SQL_CACHE_SIZE.

setMaximumSize

added in version 1.1.0

long setMaximumSize (long numBytes)

Sets the maximum size the database will grow to. The maximum size cannot be set below the current size.

Parameters
numBytes	long: the maximum database size, in bytes

Returns
long	the new maximum database size

setPageSize

added in version 1.1.0

void setPageSize (long numBytes)

Sets the database page size. The page size must be a power of two. This method does not work if any data has been written to the database file, and must be called right after the database has been created.

Parameters
numBytes	long: the database page size, in bytes

setTransactionSuccessful

added in version 1.1.0

void setTransactionSuccessful ()

Marks the current transaction as successful. Do not do any more database work between calling this and calling endTransaction. Do as little non-database work as possible in that situation too. If any errors are encountered between this and endTransaction the transaction will still be committed.

Throws
IllegalStateException	if the current thread is not in a transaction or the transaction is already marked as successful.

setVersion

added in version 1.1.0

void setVersion (int version)

Sets the database version.

Parameters
version	int: the new database version

update

added in version 1.1.0

int update (String table, 
                int conflictAlgorithm, 
                ContentValues values, 
                String whereClause, 
                Object[] whereArgs)

Convenience method for updating rows in the database.

Parameters
table	String: the table to update in
conflictAlgorithm	int: for update conflict resolver. One of CONFLICT_NONE, CONFLICT_ROLLBACK, CONFLICT_ABORT, CONFLICT_FAIL, CONFLICT_IGNORE, CONFLICT_REPLACE.
values	ContentValues: a map from column names to new column values. null is a valid value that will be translated to NULL.
whereClause	String: the optional WHERE clause to apply when updating. Passing null will update all rows.
whereArgs	Object: You may include ?s in the where clause, which will be replaced by the values from whereArgs. The values will be bound as Strings.

Returns
int	the number of rows affected

yieldIfContendedSafely

added in version 1.1.0

boolean yieldIfContendedSafely (long sleepAfterYieldDelay)

Temporarily end the transaction to let other threads run. The transaction is assumed to be successful so far. Do not call setTransactionSuccessful before calling this. When this returns a new transaction will have been created but not marked as successful. This assumes that there are no nested transactions (beginTransaction has only been called once) and will throw an exception if that is not the case.

Parameters
sleepAfterYieldDelay	long: if > 0, sleep this long before starting a new transaction if the lock was actually yielded. This will allow other background threads to make some more progress than they would if we started the transaction immediately.

Returns
boolean	true if the transaction was yielded

yieldIfContendedSafely

added in version 1.1.0

boolean yieldIfContendedSafely ()

Temporarily end the transaction to let other threads run. The transaction is assumed to be successful so far. Do not call setTransactionSuccessful before calling this. When this returns a new transaction will have been created but not marked as successful. This assumes that there are no nested transactions (beginTransaction has only been called once) and will throw an exception if that is not the case.

Returns
boolean	true if the transaction was yielded

• Interfaces

  • SupportSQLiteDatabase
  • SupportSQLiteOpenHelper
  • SupportSQLiteOpenHelper.Factory
  • SupportSQLiteProgram
  • SupportSQLiteQuery
  • SupportSQLiteStatement

• Classes

  • SimpleSQLiteQuery
  • SupportSQLiteOpenHelper.Callback
  • SupportSQLiteOpenHelper.Configuration
  • SupportSQLiteOpenHelper.Configuration.Builder
  • SupportSQLiteQueryBuilder