SupportSQLiteDatabase

public interface SupportSQLiteDatabase
implements Closeable

androidx.sqlite.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.

default void execPerConnectionSQL(String sql, Object[] bindArgs)

Execute the given SQL statement on all connections to this database.

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.

default boolean isExecPerConnectionSQLSupported()

Returns true if execPerConnectionSQL(String, Object[]) is supported by the implementation.

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(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 Cursor query(SupportSQLiteQuery query)

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

Public methods

beginTransaction

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract SupportSQLiteStatement compileStatement (String sql)

Compiles the given SQL statement.

Parameters
sql String: The sql query.

Returns
SupportSQLiteStatement Compiled statement.

delete

public abstract 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

public abstract 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.

enableWriteAheadLogging

public abstract 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 SQLiteDatabase.ENABLE_WRITE_AHEAD_LOGGING flag to SQLiteDatabase.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.

endTransaction

public abstract void endTransaction ()

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

execPerConnectionSQL

public void execPerConnectionSQL (String sql, 
                Object[] bindArgs)

Execute the given SQL statement on all connections to this database.

This statement will be immediately executed on all existing connections, and will be automatically executed on all future connections.

Some example usages are changes like PRAGMA trusted_schema=OFF or functions like SELECT icu_load_collation(). If you execute these statements using execSQL(String) then they will only apply to a single database connection; using this method will ensure that they are uniformly applied to all current and future connections.

An implementation of SupportSQLiteDatabase might not support this operation. Use isExecPerConnectionSQLSupported() to check if this operation is supported before calling this method.

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

bindArgs Object: The arguments that should be bound to the SQL statement.

Throws
UnsupportedOperationException if this operation is not supported. To check if it supported use isExecPerConnectionSQLSupported()

execSQL

public abstract 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

execSQL

public abstract 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

getAttachedDbs

public 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.

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

getMaximumSize

public abstract long getMaximumSize ()

Returns the maximum size the database may grow to.

Returns
long the new maximum database size

getPageSize

public abstract long getPageSize ()

Returns the current database page size, in bytes.

Returns
long the database page size, in bytes

getPath

public abstract String getPath ()

Gets the path to the database file.

Returns
String The path to the database file.

getVersion

public abstract int getVersion ()

Gets the database version.

Returns
int the database version

inTransaction

public abstract boolean inTransaction ()

Returns true if the current thread has a transaction pending.

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

insert

public abstract 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 SQLiteDatabase.CONFLICT_NONE, SQLiteDatabase.CONFLICT_ROLLBACK, SQLiteDatabase.CONFLICT_ABORT, SQLiteDatabase.CONFLICT_FAIL, SQLiteDatabase.CONFLICT_IGNORE, SQLiteDatabase.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

public 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.

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

public abstract 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.

isExecPerConnectionSQLSupported

public boolean isExecPerConnectionSQLSupported ()

Returns true if