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

Database

Methods10
Constructs
DestructorConstructor
Methods - Instance
commitTransactiondestroyTabledestroyTablesexecuteBatchSqlexecuteSqlisTableExistrollbackTransactionstartTransaction
Examples3
Using TransactionsOpen and close databasedestroyTables

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.

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.

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.

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.

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.

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

Parameters

  • dbPath : STRING

    The path to the database. Databases stored at the path provided by 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.

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.

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.

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.

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.new
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()

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.

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'])