RDB Development

When to Use

A relational database (RDB) store allows you to manage local data with or without native SQL statements based on SQLite.

Available APIs

Most of the RDB store APIs are asynchronous interfaces, which can use a callback or promise to return the result. This document uses the promise-based APIs as an example. For details about the APIs, see Relational Database.

Creating or Deleting an RDB Store

The following table describes the APIs available for creating and deleting an RDB store.

Table 1 APIs for creating and deleting an RDB store

Managing Data in an RDB Store

The RDB module provides APIs for inserting, deleting, updating, and querying data in a local RDB store.

• Inserting Data

  The RDB module provides APIs for inserting data through a ValuesBucket in a data table. If the data is inserted, the row ID of the data inserted will be returned; otherwise, -1 will be returned.

  Table 2 API for inserting data

• Updating Data

  Call the update() method to pass new data and specify the update conditions by using RdbPredicates. If the data is updated, the number of rows of the updated data will be returned; otherwise, 0 will be returned.

  Table 3 API for updating data

• Deleting Data

  Call the delete() method to delete data meeting the conditions specified by RdbPredicates. If the data is deleted, the number of rows of the deleted data will be returned; otherwise, 0 will be returned.

  Table 4 API for deleting data

• Querying data

  You can query data in an RDB store in either of the following ways:

  • Call the query() method to query data based on the predicates, without passing any SQL statement.
  • Run the native SQL statement.

  Table 5 APIs for querying data

Using Predicates

The RDB module provides RdbPredicates for you to set database operation conditions.

The following table lists common predicates. For more information about predicates, see RdbPredicates.

Table 6 APIs for using RDB store predicates

Using the Result Set

A result set can be regarded as a row of data in the queried results. It allows you to traverse and access the data you have queried.

For details about how to use result set APIs, see Result Set.

NOTICE
After a result set is used, you must call the close() method to close it explicitly.

Table 7 APIs for using the result set

Setting Distributed Tables

Setting Distributed Tables

Table 8 API for setting distributed tables

Obtaining the Distributed Table Name for a Remote Device

You can obtain the distributed table name for a remote device based on the local table name. The distributed table name can be used to query the RDB store of the remote device.

Table 9 API for obtaining the distributed table name of a remote device

Synchronizing Data Between Devices

Table 10 API for synchronizing data between devices

Registering an RDB Store Observer

Table 11 API for registering an observer

Unregistering an RDB Store Observer

Table 12 API for unregistering an observer

How to Develop

1. Create an RDB store.

   1. Configure the RDB store attributes, including the RDB store name, storage mode, and whether read-only mode is used.
   2. Initialize the table structure and related data in the RDB store.
   3. Create an RDB store.

   The sample code is as follows:

   import data_rdb from '@ohos.data.rdb'
   
   const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (" + "id INTEGER PRIMARY KEY AUTOINCREMENT, " + "name TEXT NOT NULL, " + "age INTEGER, " + "salary REAL, " + "blobType BLOB)";
   const STORE_CONFIG = {name: "rdbstore.db"}
   data_rdb.getRdbStore(STORE_CONFIG, 1, function (err, rdbStore) {
       rdbStore.executeSql(CREATE_TABLE_TEST )
       console.info('create table done.')
   })
   

2. Insert data.

   1. Create a ValuesBucket to store the data you need to insert.
   2. Call the insert() method to insert data into the RDB store.

   The sample code is as follows:

   var u8 = new Uint8Array([1, 2, 3])
   const valueBucket = {"name": "Tom", "age": 18, "salary": 100.5, "blobType": u8}
   let insertPromise = rdbStore.insert("test", valueBucket)
   

3. Query data.

   1. Create an RdbPredicates object to specify query conditions.
   2. Call the query() method to query data.
   3. Call the ResultSet() method to obtain the query result.

   The sample code is as follows:

   let predicates = new data_rdb.RdbPredicates("test");
   predicates.equalTo("name", "Tom")
   let promisequery = rdbStore.query(predicates)
       promisequery.then((resultSet) => {
       resultSet.goToFirstRow()
       const id = resultSet.getLong(resultSet.getColumnIndex("id"))
       const name = resultSet.getString(resultSet.getColumnIndex("name"))
       const age = resultSet.getLong(resultSet.getColumnIndex("age"))
       const salary = resultSet.getDouble(resultSet.getColumnIndex("salary"))
       const blobType = resultSet.getBlob(resultSet.getColumnIndex("blobType"))
       resultSet.close()
   })
   

4. Set the distributed tables to be synchronized.

   1. Set the distributed tables.
   2. Check whether the setting is successful.

   The sample code is as follows:

   let promise = rdbStore.setDistributedTables(["test"])
   promise.then(() => {
       console.info("setDistributedTables success.")
   }).catch((err) => {
       console.info("Failed to set distributed tables.")
   })
   

5. Synchronize data across devices.

   1. Construct an RdbPredicates object to specify remote devices within the network to be synchronized.
   2. Call the sync() method to synchronize data.
   3. Check whether the data synchronization is successful.

   The sample code is as follows:

   let predicate = new data_rdb.RdbPredicates('test')
   predicate.inDevices(['12345678abcde'])
   let promise = rdbStore.sync(rdb.SyncMode.SYNC_MODE_PUSH, predicate)
   promise.then((result) => {
       console.log('sync done.')
       for (let i = 0; i < result.length; i++) {
           console.log('device=' + result[i][0] + ' status=' + result[i][1])
       }
   }).catch((err) => {
       console.log('sync failed')
   })
   

6. Subscribe to distributed data.

   1. Register an observer to listen for distributed data changes.
   2. When data in the RDB store changes, a callback will be invoked to return the data changes.

   The sample code is as follows:

   function storeObserver(devices) {
       for (let i = 0; i < devices.length; i++) {
           console.log('device=' + devices[i] + ' data changed')
       }
   }
   try {
       rdbStore.on('dataChange', rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver)
   } catch (err) {
       console.log('Failed to register observer')
   }
   

7. Query data across devices.

   1. Obtain the distributed table name for a remote device based on the local table name.
   2. Call the ResultSet() method to obtain the query result.

   The sample code is as follows:

   let tableName = rdbStore.obtainDistributedTableName(deviceId, "test");
   let resultSet = rdbStore.querySql("SELECT * FROM " + tableName)