RDB Development

When to Use

On the basis of the SQLite database, the relational database (RDB) allows you to operate data with or without native SQL statements. In OpenHarmony, an RDB is also called RDB store.

Available APIs

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 provides APIs for inserting, deleting, updating, and querying data in the local RDB store.

• Inserting data

  The RDB 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 APIs 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 APIs 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 APIs 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 provides RdbPredicates for you to set database operation conditions.

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. The following table describes the external APIs of ResultSet.

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 APIs 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 APIs for obtaining the distributed table name of a remote device

Synchronizing Data Between Devices

Table 10 APIs 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 the 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(SQL_CREATE_TABLE)
       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("setDistributedTables failed.")
   })
   

5. Synchronize data across devices.

   1. Constructs 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=' + device[i] + ' data changed')
       }
   }
   try {
       rdbStore.on('dataChange', rdb.SubscribeType.SUBSCRIBE_TYPE_REMOTE, storeObserver)
   } catch (err) {
       console.log('register observer failed')
   }
   

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)
   

Samples

The following samples are provided for you to better understand the RDB development:

• Rdb: eTS RDB (API8)
• DistributedRdb: eTS Distributed Relational Database (API8)
• Relational Database