RDB Development

When to Use

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

Available APIs

Creating and Deleting an RDB Store

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

Table 1 APIs for creating and deleting an RDB store

Encrypting an RDB Store

The RDB provides the database encryption capability. When creating an RDB store, you can add a key for security purposes. After that, the RDB store can be accessed only with the correct key.

Table 2 API for changing the key

Using Predicates

The RDB provides AbsRdbPredicates for you to set database operation conditions. The AbsRdbPredicates has the following child classes:

• RdbPredicates: With this class, you do not need to write complex SQL statements. Instead, you can combine SQL statements simply by calling methods in this class, such as equalTo, notEqualTo, groupBy, orderByAsc, and beginsWith.

• RawRdbPredicates: With this class, you can set whereClause and whereArgs, but cannot call methods such as equalTo.

  Table 3 APIs for RDB store predicates

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 an API for inserting data through ValuesBucket in a data table. If the data is added, the row number of the data inserted is returned; otherwise, -1 is returned.

  Table 4 APIs for inserting data tables

• Deleting data

  Call the delete() method to delete data meeting the conditions specified by AbsRdbPredicates. If the data is deleted, the row number of the deleted data is returned; otherwise, 0 is returned.

  Table 5 API for deleting data

• Updating data

  Call the update() method to modify data based on the passed data and the conditions specified by AbsRdbPredicates. If the data is updated, the row number of the updated data is returned; otherwise, 0 is returned.

  Table 6 API for updating 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 7 APIs for querying data

Using the Result Set

A result set can be regarded as rows 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.

Table 8 APIs for using the result set

Setting a List of Distributed Tables

You can set a list of distributed tables for data operations across devices.

Table 9 API for setting a distributed table list

Obtaining the Distributed Table Name for a Remote Device

When querying the RDB store of a remote device, you need to use the distributed table name. You can obtain the distributed table name of a remote device based on the local table name.

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

Synchronizing Data Between Devices

Table 11 API for cross-device data synchronization

Registering an RDB Store Observer

Table 12 API for registering an observer

Unregistering an RDB Store Observer

Table 13 API for unregistering an observer

Constraints

None.

How to Develop

1. Create an RDB store.

   a. Configure the RDB store attributes, including the RDB store name, storage mode, and read-only mode.

   b. Initialize the table structure and related data in the RDB store.

   c. Create an RDB store.

   The sample code is as follows:

   const std::string DATABASE_NAME = RDB_TEST_PATH + "RdbStoreTest.db";
   const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, salary REAL, blobType BLOB)";
   
   class OpenCallback : public RdbOpenCallback {
   public:
       int OnCreate(RdbStore &rdbStore) override;
       int OnUpgrade(RdbStore &rdbStore, int oldVersion, int newVersion) override;
   };
   
   int OpenCallback::OnCreate(RdbStore &store)
   {
       return store.ExecuteSql(CREATE_TABLE_TEST);
   }
   
   RdbStoreConfig config(DATABASE_NAME);
   OpenCallback callback;
   
   std::shared_ptr<RdbStore> store = RdbHelper::GetRdbStore(config, 1, callback, 0); 
   

2. Insert data.

   a. Create a ValuesBucket to store the data you need to insert.

   b. Call the insert() method to insert data into the RDB store.

   c. Create an RDB store.

   The sample code is as follows:

   ValuesBucket values;
   
   values.PutInt("id", 1);
   values.PutString("name", std::string("Tom"));
   values.PutInt("age", 18);
   values.PutDouble("salary", 100.5);
   values.PutBlob("blobType", std::vector<uint8_t>{ 1, 2, 3 });
   store->Insert(id, "test", values);
   

3. Query data.

   a. Create a predicate that specifies query conditions.

   b. Specify the data columns to return in the result set.

   c. Call the query() method to query data.

   d. Call the ResultSet APIs to traverse data in the result set.

   The sample code is as follows:

   std::vector<std::string> columns = {"id", "name", "age", "salary"};
   
   RdbPredicates predicates("test");
   predicates.EqualTo("age", "25")->OrderByAsc("salary");
   std::unique_ptr<ResultSet> resultSet  = store->Query(predicates, columns)
   resultSet.goToNextRow();
   

4. Set the distributed tables to be synchronized.

   Call the SetDistributedTables() method to set the distributed tables to be synchronized.

   The sample code is as follows:

   store->SetDistributedTables("test");
   

5. Synchronize data.

   a. Set the data synchronization mode and block status.

   b. Constructs an AbsPredicates object to specify remote devices within the network to be synchronized.

   c. Call the Sync() method to synchronize data.

   The sample code is as follows:

   SyncOption option;
   option.mode = PUSH;
   option.isBlock = true;
   AbsRdbPredicates predicate("test");
   predicate.InAllDevices();
   store->Sync(option, predicate, [] (const SyncResult& result) {
       for (const auto& [device, status] : result) {
           LogI("device=%s status=%d", device.c_str(), status);
       }
   });
   

6. Subscribe to distributed data.

   a. Override the OnChange() function.

   b. Define the distributed data subscription type.

   c. Call APIs to subscribe to or unsubscribe from distributed data.

   The sample code is as follows:

   class MyObserver : public RdbStoreObserver {
   public:
       void OnChange(const std::vector<std::string>& devices) override {
           for (const auto& device : devices) {
               LOGI("device=%s data change", device.c_str());
           }
       }
   };
   
   SubscribeOption option;
   option.mode = SubscribeMode::REMOTE;
   MyObserver observer;
   store->Subscribe(option, &observer); // Subscribe to distributed data.
   
   store->UnSubscribe(option, &observer); // Unsubscribe from distributed data.
   

7. Query data across devices.

   a. Obtain the distributed table name for a remote device based on the local table name.

   b. Run SQL statements to query data in the RDB store of the remote device.

   The sample code is as follows:

    std::string tableName = store->ObtainDistributedTableName("123456789abcd", "test");
    auto resultSet = store->QuerySql("SELECT * from ?;", tableName);