HarperDB Instance w/ React

HarperDB Instance w/ React

HarperDB is a distributed database focused on making data management easy. It supports both SQL and NoSQL queries. Besides building REST APIs with server-side technologies(Catalin Pit's Build A REST API With HarperDB and FastifyJS), it also offers to access the database instance directly inside the client-side application.

In this article, we'll learn how to set up the HarperDB Cloud instance & access it directly inside a React App.

Setting up HarperDB Cloud Instance

First, you need to Sign up for a free HarperDB Cloud instance:


After signing up, you'll have the access to the dashboard below. To create a new instance, click on the + button:


Next, click on Create HarperDB Cloud Instance:


Fill in the details regarding the instance:


Finally, select the Instance specs and confirm the details:


Once the instance is created, it will be added to the dashboard:

Screenshot 2021-06-06 at 8.45.13 PM.png

Click on the instance card and you'll be asked to add a schema:


A schema 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 from the HarperDB instance. Let's proceed with creating a schema and a table inside it.

Screenshot 2021-06-06 at 9.43.28 PM.png

Adding new records to the table:


On saving, we have the records added:


Note: The timestamp fields - __createdtime__ and __updatedtime__ are auto-generated by HarperDB.

Our instance is ready to be used in a client-side application.

Integrating HarperDB Cloud Instance in a React App

Setting up the React App:

npx create-react-app harperdb-react-demo
cd harperdb-react-demo

Install use-harperdb - a React Hook for accessing HarperDB:

npm i use-harperdb --save

Next, create a .env file at the root of the project with the following variables:


Now, wrap the App component with the provider -HarperDBProvider and provide the needed attributes - url, user and password:

import React from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";
import reportWebVitals from "./reportWebVitals";
import { HarperDBProvider } from "use-harperdb";

      <App />

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals

Create a child component say - Bloggers.js and this is where you'll access the data. To get the data, you need to make a call to useHarperDB hook with the query object.

The SQL query - select * from hashnode.blogs will get all the records inside the table blogs belonging to the hashnode schema. The hook returns an array with elements - data, loading, error, refresh. Use destructuring to unpack the values:

import React from 'react';
import { useHarperDB } from 'use-harperdb';

function Bloggers() {
    const [data, loading, error, refresh] = useHarperDB({
        query: { operation: 'sql', sql: `select * from hashnode.blogs` },

    return (

export default Bloggers;

Let’s work on displaying the data and handling loading & error:

import React from 'react';
import { useHarperDB } from 'use-harperdb';
import './Bloggers.css';

function Bloggers() {
    const [data, loading, error, refresh] = useHarperDB({
        query: { operation: 'sql', sql: `select * from hashnode.blogs` },
    if (loading) {
        return <div>Loading...</div>

    if(data && data.length > 0) {
        return (
                {data.map((blog) => {
                  return (
                    <tr key={blog.id}>
                         <a href={blog.URL} 
            <button onClick={refresh}>Refresh</button>
    } else {
        return (

export default Bloggers;

Let's walk through the above code:

  • if loading: rendered a div with loading text.
  • if data exists & the returned array isn't empty: rendered the data in a tabular form.
  • if error: rendered the error.
  • if clicked on Refresh, data will be fetched again.

And after adding some basic styles, this is what we get:


You can also enable auto-refresh feature by simply passing the second property interval in the object passed to the hook:

const [data, loading, error, refresh] = useHarperDB({
        query: { operation: 'sql', sql: `select * from hashnode.blogs` },
        interval: 5000

Now, there will be a refresh after every 5 seconds. That's all for this article.


The objective of this article was to learn how to set up the HarperDB Cloud instance & access it directly inside a React App using the use-harperdb hook. Hope you find it useful for the ongoing hackathon.


Did you find this article valuable?

Support Piyush Sinha by becoming a sponsor. Any amount is appreciated!