HarperDB Cloud is a database service that supports both SQL and NoSQL queries for CRUD operations. It needs minimal configuration to get started and its realm is not only limited to build REST APIs with a server-side technology such as Node.js.
HarperDB offers a way to access the database cloud instance directly in your client-side application. It has a built-in HTTP API that allows us to query data directly.
In this post, let’s take a look at how we configure a HarperDB Cloud database instance and fetch the data by querying the database within a Reactjs app. HarperDB provides a React Hook, known as useHarperDB to make our jobs easier.
HarperDB Instance Glossary
This post is going to use a similar instance of the HarperDB database that we built using the REST API approach with Node.js in our previous post. Please take a look at the post on how to set up the cloud instance here. This way you will have a populated table of data fields.
The schema in the above database instance is called
dev. A schema in HarperDB is necessary. It is equivalent to a collection of tables. Without an existing schema, you cannot create a new table and without a table, you cannot add or update data in the HarperDB instance.
Below the schema, there is an option to add one or more tables. In the above instance, there is a table already created and is called
outlets. This table has a unique identifier
id for each row of data.
On the right-hand side, you will find the data inside the table. Do notice the two timestamp fields. They are auto inserted by HarperDB whenever a new row adds to the table and is auto-maintained.
- createdtime: to record the timestamp when data is inserted.
- updatedtime: to record the timestamp when any data field is updated for the last time.
Once you have set up the cloud instance, make sure to use a React project with the library’s version
Start by creating a new React app. We are going to use this React app for building the example app in this post. Open up a terminal window and execute the following command:
Now you can start the development server to see the React app in action. Go to the terminal window and execute the command
yarn start. You are going to get the following output in a browser window at URL:
Creating a User With Custom Roles
By default, the user created in the HarperDB Cloud instance is a superuser. It has admin rights to query and add data and rights to create and drop the table from the existing schema as well as create and drop new schemas. In a client-side application, we do not want to have a superuser. Since most client apps are public, this is never a good approach to use the default user.
The approach to resolve this is to create a new user that has the right to only perform CRUD operations inside a data table. HarperDB provides a way to define custom user roles as well as create a new user using that role.
Start by opening your cloud instance and go to the tab
roles from the menu bar.
Here you can define a new standard role to create a custom one. Let’s call this new role,
Once the new role is created, the instance prompts with the permissions we can assign to any user with this role. You are now allowed to configure the access to tables and schemas for this specific role. There is only one schema right now and inside it, there is only one data table. For this example, let’s keep the default configuration and proceed by pressing the button Update Role Permissions.
Once the permissions are updated, go to the tab
users next to the
roles in the menu bar. This is used to add a new user with the custom role just created. From the drop-down menu, select the role
Click the Add user button to add the new user.
Now, we can use this custom user in the client React app to query the data from the table
Integrating HarperDB in a React
use-harperdb hook comes with a
HarperDBProvider that is used to wrap the instance of the React app or the
App component in general inside the
index.js file. This is mandatory to execute a CRUD operation on the database instance.
Add the following import statement inside
To execute any CRUD operation on the database instance, the provider requires the DB instance URL, the username, and the password associated with that user. We are going to make use of environmental variables to add these values.
Create a new file called
.env at the root of the React project with the following variables. The values of these variables are mentioned as a description in
 but you must replace the square brackets and your own values.
Create React App reads any environmental variables that are prefixed with
REACT_APP. Instead of using a third-party library, we can directly use these environmental variables to provide necessary attributes to
That’s it. We have successfully configured the React app to use the HarperDB database instance.
Querying the Data From HarperDB
To query the data from the database instance in the React app, the
useHarperDB hook provides elements to do so.
App.js file and import the hook from
use-harperdb. Let’s also set up a basic UI to display data when fetched.
The rule for using any hook is that they can only be consumed inside a functional component. The
useHarperDB hook gives an array with elements to query the
data which is returned as an array. It also provides:
loadingwhere you can let the user know if the query is running the data is not yet loaded.
errordetermines if there is an error when querying the data.
refreshit is a function that allows fetching the data.
To query the data from the database instance, pass the object inside the hook.
Add the following snippet query in the
App.js file to fetch all the data from the database.
In the above snippet, the second property of
interval passed is optional to use when you don’t want to explicitly use the
refresh function. It accepts a value in milliseconds.
Let’s add some JSX for
error by using
if/else syntax inside the
For a very brief moment, you may see the loading message being displayed.
Also, if you are passing
interval as the second property, you may notice that after every 5 seconds, the React app automatically refreshes the web page. To stop this behavior, you can remove the
map function, let’s map over the array of
data and display the contents. If data is fetched that means it exists and we can easily map over the array. Add the following code snippet in place of the comment.
Go back to the browser window and you will get the following result:
The query can also be made using the
useHarperdb hook with only the
data array. Add the following query to fetch the total number of outlets or records from the database.
To display the total count, add the modify the JSX rendered from
Here is the output after this step:
Hooks are a great addition to the React world and they certainly help us write less code. The objective of this post was to introduce you to the
useHarperDB hook and how to integrate it into a React app to fetch the data from a database hosted in the cloud.