SQLiteOpenHelper

SQLiteOpenHelper(
    context: Context?, 
    name: String?, 
    factory: SQLiteDatabase.CursorFactory?, 
    version: Int)

Create a helper object to create, open, and/or manage a database. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase or getReadableDatabase is called.

SQLiteOpenHelper

SQLiteOpenHelper(
    context: Context?, 
    name: String?, 
    factory: SQLiteDatabase.CursorFactory?, 
    version: Int, 
    errorHandler: DatabaseErrorHandler?)

Create a helper object to create, open, and/or manage a database. The database is not actually created or opened until one of getWritableDatabase or getReadableDatabase is called.

Accepts input param: a concrete instance of DatabaseErrorHandler to be used to handle corruption when sqlite reports database corruption.

SQLiteOpenHelper

SQLiteOpenHelper(
    context: Context?, 
    name: String?, 
    version: Int, 
    openParams: SQLiteDatabase.OpenParams)

Create a helper object to create, open, and/or manage a database. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase or getReadableDatabase is called.

close

open fun close(): Unit

Close any open database object.

getDatabaseName

open fun getDatabaseName(): String!

Return the name of the SQLite database being opened, as given to the constructor.

getReadableDatabase

open fun getReadableDatabase(): SQLiteDatabase!

Create and/or open a database. This will be the same object returned by getWritableDatabase unless some problem, such as a full disk, requires the database to be opened read-only. In that case, a read-only database object will be returned. If the problem is fixed, a future call to getWritableDatabase may succeed, in which case the read-only database object will be closed and the read/write object will be returned in the future.

Like getWritableDatabase, this method may take a long time to return, so you should not call it from the application main thread, including from ContentProvider.onCreate().

getWritableDatabase

open fun getWritableDatabase(): SQLiteDatabase!

Create and/or open a database that will be used for reading and writing. The first time this is called, the database will be opened and onCreate, onUpgrade and/or onOpen will be called.

Once opened successfully, the database is cached, so you can call this method every time you need to write to the database. (Make sure to call close when you no longer need the database.) Errors such as bad permissions or a full disk may cause this method to fail, but future attempts may succeed if the problem is fixed.

Database upgrade may take a long time, you should not call this method from the application main thread, including from ContentProvider.onCreate().

onCreate

abstract fun onCreate(db: SQLiteDatabase!): Unit

Called when the database is created for the first time. This is where the creation of tables and the initial population of the tables should happen.

onDowngrade

open fun onDowngrade(
    db: SQLiteDatabase!, 
    oldVersion: Int, 
    newVersion: Int
): Unit

Called when the database needs to be downgraded. This is strictly similar to onUpgrade method, but is called whenever current version is newer than requested one. However, this method is not abstract, so it is not mandatory for a customer to implement it. If not overridden, default implementation will reject downgrade and throws SQLiteException

This method executes within a transaction. If an exception is thrown, all changes will automatically be rolled back.

onOpen

open fun onOpen(db: SQLiteDatabase!): Unit

Called when the database has been opened. The implementation should check SQLiteDatabase.isReadOnly before updating the database.

This method is called after the database connection has been configured and after the database schema has been created, upgraded or downgraded as necessary. If the database connection must be configured in some way before the schema is created, upgraded, or downgraded, do it in onConfigure instead.

onUpgrade

abstract fun onUpgrade(
    db: SQLiteDatabase!, 
    oldVersion: Int, 
    newVersion: Int
): Unit

Called when the database needs to be upgraded. The implementation should use this method to drop tables, add tables, or do anything else it needs to upgrade to the new schema version.

The SQLite ALTER TABLE documentation can be found here. If you add new columns you can use ALTER TABLE to insert them into a live table. If you rename or remove columns you can use ALTER TABLE to rename the old table, then create the new table and then populate the new table with the contents of the old table.

This method executes within a transaction. If an exception is thrown, all changes will automatically be rolled back.

Important: You should NOT modify an existing migration step from version X to X+1 once a build has been released containing that migration step. If a migration step has an error and it runs on a device, the step will NOT re-run itself in the future if a fix is made to the migration step.

For example, suppose a migration step renames a database column from foo to bar when the name should have been baz. If that migration step is released in a build and runs on a user's device, the column will be renamed to bar. If the developer subsequently edits this same migration step to change the name to baz as intended, the user devices which have already run this step will still have the name bar. Instead, a NEW migration step should be created to correct the error and rename bar to baz, ensuring the error is corrected on devices which have already run the migration step with the error.

setLookasideConfig

open fun setLookasideConfig(
    slotSize: Int, 
    slotCount: Int
): Unit

Configures lookaside memory allocator

This method should be called from the constructor of the subclass, before opening the database, since lookaside memory configuration can only be changed when no connection is using it

SQLite default settings will be used, if this method isn't called. Use setLookasideConfig(0,0) to disable lookaside

Note: Provided slotSize/slotCount configuration is just a recommendation. The system may choose different values depending on a device, e.g. lookaside allocations can be disabled on low-RAM devices

setWriteAheadLoggingEnabled

open fun setWriteAheadLoggingEnabled(enabled: Boolean): Unit

Enables or disables the use of write-ahead logging for the database. Write-ahead logging cannot be used with read-only databases so the value of this flag is ignored if the database is opened read-only.