Setting up a database for your app

Required setup

Users of SquiDB create a subclass of SquidDatabase to manage database administration. SquidDatabase handles all the business logic of opening/closing the database and triggering migrations when the db version has changed and needs to be upgraded. Your custom subclass of it only needs to implement a few abstract methods to be up and running.

Required methods:

String getName(); // The name to use for the database file.

int getVersion(); // The current database version.
                  // If this value is incremented between database opens, a migration will be triggered

Table[] getTables(); // Return the tables that should be created when initializing a new database

void onUpgrade(ISQLiteDatabase db, int oldVersion, int newVersion); // Handle database upgrades

// This method is responsible for creating a low-level, platform-specific SQLite object. This method
// can return e.g. an AndroidOpenHelper from the squidb-android module when running on Android, or
// an IOSOpenHelper from the squidb-ios module when running on iOS.
ISQLiteOpenHelper createOpenHelper(String databaseName, OpenHelperDelegate delegate, int version);

Optional setup

There are several optional methods you can override as well. Here are some common ones:

View[] getViews(); // Like getTables(), but for SQL views. Return the Views that should be created.

Index[] getIndexes(); // Return any Indexes that should be created when initializing a new database.

void onTablesCreated(ISQLiteDatabase db); // Called after tables (and other database members)
                                         // have been created when initializing a new database

void onError(String message, Throwable error); // The default implementation logs errors

For a complete list of protected methods your SquidDatabase subclass can override, see the SquidDatabase javadocs.

It is highly recommended that you create your SquidDatabase subclass instances as singletons, one per database. This will save you a ton of hassle trying to debug concurrent DB access. Just make them singletons and you won't have to worry about it.

---

See also:

• Defining table schemas
• Implementing database upgrades
• Using SquidDatabase