Share via


SQLiteDatabase.EnableWriteAheadLogging Method

Definition

This method enables parallel execution of queries from multiple threads on the same database.

[Android.Runtime.Register("enableWriteAheadLogging", "()Z", "GetEnableWriteAheadLoggingHandler")]
public virtual bool EnableWriteAheadLogging ();
[<Android.Runtime.Register("enableWriteAheadLogging", "()Z", "GetEnableWriteAheadLoggingHandler")>]
abstract member EnableWriteAheadLogging : unit -> bool
override this.EnableWriteAheadLogging : unit -> bool

Returns

True if write-ahead logging is enabled.

Attributes

Exceptions

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.

Remarks

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. This is more efficient than calling #enableWriteAheadLogging. <pre> SQLiteDatabase db = SQLiteDatabase.openDatabase("db_filename", cursorFactory, SQLiteDatabase.CREATE_IF_NECESSARY | SQLiteDatabase.ENABLE_WRITE_AHEAD_LOGGING, myDatabaseErrorHandler); </pre>

Another way to enable write-ahead logging is to call #enableWriteAheadLogging after opening the database. <pre> SQLiteDatabase db = SQLiteDatabase.openDatabase("db_filename", cursorFactory, SQLiteDatabase.CREATE_IF_NECESSARY, myDatabaseErrorHandler); db.enableWriteAheadLogging(); </pre>

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

Java documentation for android.database.sqlite.SQLiteDatabase.enableWriteAheadLogging().

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to

See also