SQLiteDatabase.EnableWriteAheadLogging Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Write-ahead logging enables parallel execution of queries from multiple threads on the same database, and reduces the likelihood of stalling on filesystem syncs.
[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 -> boolReturns
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
Write-ahead logging enables parallel execution of queries from multiple threads on the same database, and reduces the likelihood of stalling on filesystem syncs. Write-ahead logging is significantly faster in most scenarios.
<h3>Benefits and Best Practices</h3>
Write-ahead logging is not enabled by default. However it is generally recommended for apps to enable write-ahead logging, unless the app uses SQLite features that are not compatible with write-ahead logging.
When write-ahead logging is enabled, write operations occur in a separate log file, which allows reads in other threads 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.
Another benefit of write-ahead logging is that it reduces the number of fsync calls to the underlying file system. Calling fsync may block on system locks and has poor tail latency on devices with slow filesystems.
The most efficient 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><h3>Disabling Write-ahead Logging</h3>
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.
When write-ahead logging is not enabled (the default, or after calling #disableWriteAheadLogging), 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.
Write-ahead logging slightly increases the memory usage by SQLite. You can measure the impact on memory using tools like meminfo.
<h3>Usage</h3>
After opening a database with the #ENABLE_WRITE_AHEAD_LOGGING flag or by 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.
Parallel execution of queries is performed 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. 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.
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.