Rebar iOS App Databases

Monkton, Inc.

Rebar allows for apps to have zero to many databases for managing data.

All databases classes must extend the RebarDatabase class to inherit the security configurations for each.

Internally, Rebar manages two databases for file management and internal storage and configuration.

Note At this time for iOS Core Data is not supported. Rebar ships with FMDB built in. We strongly advise against Core Data as it limits portability between developing apps to run in iOS and Android.

Setup and Instantiation

In iOS the app delegate (Which must extend the RebarAppDelegate class) class must register the databases as part of the startup process. Each database should be registered via the database manager's register method. These methods take the class value to map.

class MyAppDelegate: RebarAppDelegate {
	override func configureApp() {
		
		// Set the configuration
		RebarAppController.default.setConfiguration(MyAppAppConfiguration());

		// Set the Database configuration
		RebarDatabaseManager.default.register(MyAppDatabase.self);
		
	}
}

Using Databases in iOS

Databases can be retrieved by invoking the RebarDatabaseManager.default.getDatabase(MyAppDatabase.self) method.

Monkton has integrated FMDB into the RebarDatabaseManager as a means to provide a simple to use interface for database operations. RebarDatabase classes with the .queue databaseHandleType will return FMDatabaseQueue objects. This open source project enables queued access to the underlying databases for all database operations. FMDB also enables the interaction with the low level sqlite database instance if that is desired.

Optionally, RebarDatabase classes can override the databaseHandleType to .database which will load the database as a raw sqlite handle, not a FMDB queue.

Raw sqlite handles can be retrieved by invoking the RebarDatabaseManager.default.getRawDatabase(MyAppDatabase.self) method.

RebarDatabase classes cannot use both .queue and .database databaseHandleType types.

iOS Customization

Developers can customize the iOS database schema as they like. Databases can be provided via a default database or as a manual series of database configuration steps. Often, as developers build out apps they will need to update the schema in specific ways. Rebar provides the verifyUpgrades method in the database class to allow for this. Additionally, control of the database can be handled with the databaseName and bundlePath configurations.

For iOS and Android, as below, updates can be easily administered via the verifyUpgrades methods. This allows for the tracking and updates to tables, data, keys, each time the app is run.

For updates to the app, this is where updates to the schema should occur. Overriding this method should always call the superclass method verifyUpgrades first.

class MyAppDatabase : RebarDatabase {
	
	
	/**
		Performs the series of upgrades necessary for the app. This allows for
		schema changes to be scripted to enable dynamic updates at launch 
		time.
		
		- Parameter db: The FMDB database to have upgrades performed against
	*/
	override func verifyUpgrades(db: FMDatabase!) {
		
		// Always check the parent upgrades
		super.verifyUpgrades(queue);
		
		// Grab the current version for this database
		var currentVersion: Int = self.getCurrentDatabaseVersion(db, app: MyAppDatabase.APP_NAME);
		
		// Perform the upgrades for versions < accepted
		if (currentVersion < 1) {		
			
			performSingleUpgrade("CREATE TABLE [APP_FILE]  (ITEM_ID INTEGER PRIMARY KEY AUTOINCREMENT)", db: db);
			
	
			// Increment the current version 
			currentVersion = 2;
			
			// Update the current version
			setCurrentDatabaseVersion(db, app: MyAppDatabase.APP_NAME, version: currentVersion);
			
		}
		
	}
	
}

Database Name

Developers can control the name of the database in the app, this is a mandatory override in the app. Failure to do so will trigger a fatal exception.


class MyAppDatabase : RebarDatabase {

    /**
     Retrieves the name of the database, must be overridden in the implementing class
     
     - Returns: string for the name of the database
     */
    override var databaseName: String {
		return "my-app-db.sqlite";
	}
	
}

Bundle file

Implementations may define the source database schema with the bundlePath file. This must be a sqlite database located within the app bundle. The return value should be a string indicating the name of the file, such as myapp.sqlite. Rebar will not compare schemas and update them, they must be manually performed with the verifyUpgrades method.


class MyAppDatabase : RebarDatabase {

    /**
     The path to the database in the bundle that we will unpack for this database
     
     - Returns: The bundle path string
     */
    override var bundlePath: String {
        return "myapp.sqlite"
    }
	
}