Titanium includes a powerful database API that provides easy access to the underlying platform's SQLite implementation. Having access to Ti.Filesystem
for your app's SQLite database allows you the flexibility to handle updates, migrations, and installations more effectively.
The DbFileExt
module provides easy access to your SQLite Ti.Filesystem
object. The module also includes other convenient methods to help work with database files.
Adding the DbFileExt
module to your project is easy. Simply copy the dbfileext.js
file into your project, as shown in the following screenshot:
Once you've added the dbfileext.js
file to your project, you need to use require
to import the module into your code:
//Create our application namespace var my = { isAndroid : Ti.Platform.osname === 'android', dbfileext : require('dbfileext') };
The dbFile
function provides easy access to the Ti.Filesystem.File
object for your database. Simply provide the database name you wish to access, and the associated Ti.Filesystem.File
object will be returned:
Var myDbFile = my.dbfileext.dbFile('testdb'),
Determining your application's database folder can be challenging, as it differs according to the platform. Leveraging the dbDirectory
function assists with this challenge, providing you specify the appropriate directory path based on the device your app is running on:
my.dbfileext.dbDirectory();
You will often need to check if a database has been installed, before opening. The DbFileExt
module makes this straightforward with the dbExists
function. Simply paste in the database name and a Boolean is returned, identifying if the database has been installed:
my.dbfileext.dbExists('testdb'),
With iOS 5, Apple included the ability to back up files to the iCloud service. You can enable or disable this feature on your SQLite database file through the use of the dbRemoteBackup
function. When you provide the database name and a Boolean, you are indicating if you would like to have remote backup enabled:
my.dbfileext.dbRemoteBackup('testdb',true);
The DbFileExt
module allows you to rename your database files. This can be helpful when versioning or keeping backups of your database. To rename a database, provide the current database name and the new name as parameters to the dbRename
method, as the following statement shows:
my.dbfileext.dbRename('current name','new name'),
When dealing with large apps, or apps that require database versioning, you will often need a list of all the databases installed within your app's sandbox. The dbList
function provides the name and native path for each SQLite database within your app's database folder. You can then use this array to remove any unneeded database files:
var installedDatabase = my.dbfileext.dbList();
The next series of tests demonstrate how the DbFileExt
module works within a windowless sample app.js
.
First, we use the Ti.Database.open
function to create a sample database. The following highlighted code demonstrates how to create a database named testdb
:
//Create our application namespace
var my = {
isAndroid : Ti.Platform.osname === 'android',dbfileext : require('dbfileext')
};
var testDb = Ti.Database.open('testdb'),
Next, we build a Ti.Filesystem
object with a known reference to our testdb
database. This will later be used to verify if the DbFileExt
module is returning the correct values.
var testFileReference = (function(){ if(my.isAndroid){ return Ti.Filesystem.getFile( }else{ return testDb.file; } })();
Next, we compare the Ti.Filesystem.File
object returned by the DbFileExt
module to see if it matches our test file. These should always match no matter what the platform.
Ti.API.info("Does the module return the same as our test?"); Ti.API.info((testFileReference.nativePath === my.dbfileext.dbFile('testdb').nativePath) ? "Test Pass" : "Test Failed");
The directory where your SQLite file is installed differs by platform. For example, it is in the data
directory on Android and the Private Documents
folder on iOS. The next example demonstrates how to write the path to your devices database directory to Titanium Studio's console:
Ti.API.info("Your database directory is " + my.dbfileext.dbDirectory());
The most common use of the DbFileExt
module is to check if a database has already been installed. The next test compares the dbExists
result in DbFileExt
with those generated by our test Ti.Filesystem.File
object:
Ti.API.info("Does the exists test work?"); Ti.API.info((testFileReference.exists() === my.dbfileext.dbExists('testdb')) ? "Both Exist" : "Test Failed");
You will encounter the need to rename databases for a variety of reasons, the most common being archiving or versioning. The following highlighted code demonstrates how to rename the testdb
database to oldtest
. The dbExists
method is then called on both the new and old names to demonstrate that the rename function has worked properly.
my.dbfileext.dbRename('testdb','oldtestdb'),
Ti.API.info("Does the test db exist? " + my.dbfileext.dbExists('testdb'));
Ti.API.info("How about the oldtest one? Does that exist? " + my.dbfileext.dbExists('oldtest'));
It is often helpful to have a list of all the databases that are available within your app. This can be particularly helpful with large apps or apps containing third-party components.
To demonstrate this functionality, first we create several databases in our sample app:
Ti.Database.open('test1'), Ti.Database.open('test2'), Ti.Database.open('test3'),
The dbList
function of the DbFileExt
module is used to return all the databases installed into our app:
var installedDb = my.dbfileext.dbList();
The following snippet writes the list of databases provided by the installedDb
variable to Titanium Studio's console. This will list all of the databases used in this sample, along with any that might also be installed within your Titanium project.
installedDb.forEach(function(db) { Ti.API.info("Db Name = " + db.dbName); Ti.API.info("nativePath = " + db.nativePath); });
The final test in this recipe demonstrates how to use the dbRemove
function to delete an installed database. The following highlighted snippet shows how to delete the oldtest
database that we used earlier in the sample:
my.dbfileext.dbRemove('oldtest'),
Ti.API.info("db still exists? " + my.dbfileext.dbExists('oldtest'));
18.119.159.178