Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Database

Database is low-level API to access SQLite local database.

This API used internally by RHOM. To use RHOM, just define your models and partition databases will be created automatically.

Enabling the API

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

Destructor close()

Closes the database. The database will not be accessible until it is opened again.

Synchronous Return:

Void

Method Access:

Class Method: This method is a destructor and can only be accessed via the object that was created by the `new` constructor.
- Javascript: myObj.close()
- Ruby: @myObj.close()

commitTransaction()

Replaces: commit

Commit database transaction. Saves all updates to the database from the start of the transaction.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.commitTransaction()

destroyTable(STRING tableName)

Destroys a database table.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

tableName : STRING

Table name to destroy.

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.destroyTable(STRING tableName)

destroyTables(HASH propertyMap)

Destroy a list of database tables.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

propertyMap : HASH

include : ARRAY

Include tables.
exclude : ARRAY

Exclude tables.

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.destroyTables(HASH propertyMap)

executeBatchSql(STRING sqlStmt)

Execute a series of sql statements included in the sqlStmt string parameter.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

sqlStmt : STRING

The SQL statement.

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.executeBatchSql(STRING sqlStmt)

executeSql(STRING sqlStmt, ARRAY args)

Execute the sql statement specified in the method’s parameters.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

sqlStmt : STRING

The SQL statement.
args : ARRAY Optional

Array of the sql expressions.

Synchronous Return:

ARRAY :
Array of Hashes. Each Hash item represents record from Database.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.executeSql(STRING sqlStmt, ARRAY args)

Constructor new Rho::Database(STRING dbPath, STRING dbPartition)

This method is a constructor for this class. Instead of saying Rho.Database.initialize(dbPath,dbPartition) you would use new Rho.Database(dbPath,dbPartition). ex: var db = new Rho.Database(Rho.Application.databaseFilePath('test'), 'test'); Make sure you issue a .close() when you are finished using the database. If the database file does not exist it will be created using a SQL schema: rhodes\platform\shared\db\res\db\syncdb.schema. Do not use predefined partition names: app, user, local. Do not open the same database file in different partitions. Do not use the same partition for different database files. Do not open the same file twice.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

dbPath : STRING

The path to the database. Databases stored at the path provided by Rho::Application.databaseFilePath.
dbPartition : STRING

The database partition. Used as a file name for database and when connecting to RhoConnect server.

Synchronous Return:

Void

Method Access:

Class Method: This method is a constructor and can only be accessed via the `new` construct.
- Javascript: var myObj = new Rho.Database(STRING dbPath, STRING dbPartition)
- Ruby: @myObj = Rho::Database.new(STRING dbPath, STRING dbPartition)

isTableExist(STRING tableName)

Replaces: table_exist?

Will return true or false if the specified table exists in the current database.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Parameters

tableName : STRING

The name of the table.

Synchronous Return:

BOOLEAN

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.isTableExist(STRING tableName)

rollbackTransaction()

Replaces: rollback

Rollback database transaction. This will cancel any pending actions to the database that were executed since the last Start and before a commit.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.rollbackTransaction()

startTransaction()

Start database transaction. All operations will not be the saved to the database until a commit is executed.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.startTransaction()

Examples

Using Transactions

To insert/update multiple object/models use database transactions. This is the most performant method to initialize your application with a large set of data.

Javascript
Ruby

var db = Rho.Database;
db.startTransaction();
try
{
  for (var index in items) {
    // create hash of attribute/value pairs
    data = {
      field1 : item[index].value1, 
      field2 : item[index].value2
    }; 
    // Creates a new itemModel object and saves it
    new_item = itemModel.create(data);
  }
  
 db.commitTransaction();
}
catch
{
 db.rollbackTransaction();
}

db = Rho::Database
  db.startTransaction
  begin
    items.each do |item|
      # create hash of attribute/value pairs
      data = {
        :field1 => item['value1'], 
        :field2 => item['value2'] 
      } 
      # Creates a new itemModel object and saves it
      new_item = itemModel.create(data)
    end
   db.commitTransaction
  rescue
   db.rollbackTransaction
  end

Open and close database

The following example opens the database using the constructor method: .initialize. It then closes the database using the destructor method .close()

Javascript
Ruby

var db = new Rho.Database(Rho.Application.databaseFilePath('test'), 'test');
db.close();

db = Rho::Database.new(Rho::Application.databaseFilePath('test'), 'test')
db.close()

destroyTables

Destroy multiple tables. The following example opens the database using the constructor method: .initialize.

Javascript
Ruby

var db = new Rho.Database(...);

// destroy all tables in database
db.destroyTables({include: [], exclude: []});

// destroy specified tables
db.destroyTables({include: ['table1', 'table2'], exclude: []});

// destroy all but specified tables
db.destroyTables({include: [], exclude: ['table1', 'table2']});

db = Rho::Database.new(...)

# destroy all tables in database
db.destroyTables(:include => [], :exclude => [])

# destroy specified tables
db.destroyTables(:include => ['table1', 'table2'], :exclude => [])

# destroy all but specified tables
db.destroyTables(:include => [], :exclude => ['table1', 'table2'])