Package 

Class SQLiteOpenHelper

  • All Implemented Interfaces:
    androidx.sqlite.db.SupportSQLiteOpenHelper , java.io.Closeable , java.lang.AutoCloseable 
    
public abstract class SQLiteOpenHelper
 implements SupportSQLiteOpenHelper

    A helper class to manage database creation and version management.

    You create a subclass implementing onCreate, onUpgrade and optionally onOpen, and this class takes care of opening the database if it exists, creating it if it does not, and upgrading it as necessary. Transactions are used to make sure the database is always in a sensible state.

    This class makes it easy for android.content.ContentProvider implementations to defer opening and upgrading the database until first use, to avoid blocking application startup with long-running database upgrades.

    For an example, see the NotePadProvider class in the NotePad sample application, in the samples/ directory of the SDK.

    Note: this class assumes monotonically increasing version numbers for upgrades.

    • Constructor Detail

      • SQLiteOpenHelper

        SQLiteOpenHelper(Context context, String name, SQLiteDatabase.CursorFactory factory, int version)
        Create a helper object to create, open, and/or manage a database.This method always returns very quickly.
        Parameters:
        context - to use to open or create the database
        name - of the database file, or null for an in-memory database
        factory - to use for creating cursor objects, or null for the default
        version - number of the database (starting at 1); if the database is older,onUpgrade will be used to upgrade the database; if the database isnewer, onDowngrade will be used to downgrade the database

      • SQLiteOpenHelper

        SQLiteOpenHelper(Context context, String name, SQLiteDatabase.CursorFactory factory, int version, DatabaseErrorHandler errorHandler)
        Create a helper object to create, open, and/or manage a database.
        Parameters:
        context - to use to open or create the database
        name - of the database file, or null for an in-memory database
        factory - to use for creating cursor objects, or null for the default
        version - number of the database (starting at 1); if the database is older,onUpgrade will be used to upgrade the database; if the database isnewer, onDowngrade will be used to downgrade the database
        errorHandler - the DatabaseErrorHandler to be used when sqlite reports databasecorruption, or null to use the default error handler.

      • SQLiteOpenHelper

        SQLiteOpenHelper(Context context, String name, SQLiteDatabase.CursorFactory factory, int version, int minimumSupportedVersion, DatabaseErrorHandler errorHandler)
        Same as SQLiteOpenHelper but also accepts an integer minimumSupportedVersion as a convenience for upgrading very oldversions of this database that are no longer supported.
        Parameters:
        context - to use to open or create the database
        name - the name of the database file, null for a temporary in-memory database
        factory - to use for creating cursor objects, null for default
        version - the required version of the database
        minimumSupportedVersion - the minimum version that is supported to be upgraded to{@code version} via onUpgrade.
        errorHandler - the DatabaseErrorHandler to be used when sqlite reports databasecorruption, or null to use the default error handler.

      • SQLiteOpenHelper

        SQLiteOpenHelper(Context context, String name, String password, SQLiteDatabase.CursorFactory factory, int version, int minimumSupportedVersion, DatabaseErrorHandler errorHandler, SQLiteDatabaseHook databaseHook, boolean enableWriteAheadLogging)
        Same as SQLiteOpenHelper but also accepts an integer minimumSupportedVersion as a convenience for upgrading very oldversions of this database that are no longer supported.
        Parameters:
        context - to use to open or create the database
        name - the name of the database file, null for a temporary in-memory database
        password - for use with SQLCipher
        factory - to use for creating cursor objects, null for default
        version - the required version of the database
        minimumSupportedVersion - the minimum version that is supported to be upgraded to{@code version} via onUpgrade.
        errorHandler - the DatabaseErrorHandler to be used when sqlite reports databasecorruption, or null to use the default error handler.
        databaseHook - for preKey and postKey events with SQLCipher.

      • SQLiteOpenHelper

        SQLiteOpenHelper(Context context, String name, Array<byte> password, SQLiteDatabase.CursorFactory factory, int version, int minimumSupportedVersion, DatabaseErrorHandler errorHandler, SQLiteDatabaseHook databaseHook, boolean enableWriteAheadLogging)
        Same as SQLiteOpenHelper but also accepts an integer minimumSupportedVersion as a convenience for upgrading very oldversions of this database that are no longer supported.
        Parameters:
        context - to use to open or create the database
        name - the name of the database file, null for a temporary in-memory database
        password - for use with SQLCipher
        factory - to use for creating cursor objects, null for default
        version - the required version of the database
        minimumSupportedVersion - the minimum version that is supported to be upgraded to{@code version} via onUpgrade.
        errorHandler - the DatabaseErrorHandler to be used when sqlite reports databasecorruption, or null to use the default error handler.
        databaseHook - for preKey and postKey events with SQLCipher.

    • Method Detail

      • getDatabaseName

         String getDatabaseName()

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

      • setWriteAheadLoggingEnabled

         void setWriteAheadLoggingEnabled(boolean enabled)

        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 ofthis flag is ignored if the database is opened read-only.

        Parameters:
        enabled - True if write-ahead logging should be enabled, false if itshould be disabled.

      • getWritableDatabase

         SQLiteDatabase getWritableDatabase()

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

        Once opened successfully, the database is cached, so you cancall 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 methodto fail, but future attempts may succeed if the problem is fixed.

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

      • getReadableDatabase

         SQLiteDatabase getReadableDatabase()

        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-onlydatabase object will be returned. If the problem is fixed, a future callto getWritableDatabase may succeed, in which case the read-onlydatabase object will be closed and the read/write object will be returnedin the future.

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

      • close

         synchronized void close()

        Close any open database object.

      • onBeforeDelete

         void onBeforeDelete(SQLiteDatabase db)

        Called before the database is deleted when the version returned by getVersion is lower than the minimum supported version passed (if atall) while creating this helper. After the database is deleted, a fresh database with thegiven version is created. This will be followed by onConfigure and onCreate being called with a new SQLiteDatabase object

        Parameters:
        db - the database opened with this helper

      • onCreate

         abstract void onCreate(SQLiteDatabase db)

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

        Parameters:
        db - The database.

      • onUpgrade

         abstract void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion)

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

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

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

        Parameters:
        db - The database.
        oldVersion - The old database version.
        newVersion - The new database version.

      • onDowngrade

         void onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion)

        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 toimplement it. If not overridden, default implementation will reject downgrade andthrows SQLiteException

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

        Parameters:
        db - The database.
        oldVersion - The old database version.
        newVersion - The new database version.

      • onOpen

         void onOpen(SQLiteDatabase db)

        Called when the database has been opened. The implementationshould check isReadOnly before updating thedatabase.

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

        Parameters:
        db - The database.