HarperDB Instance w/ React

HarperDB Instance w/ React

Subscribe to my newsletter and never miss my upcoming articles

Listen to this article

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.


Interested in reading more such articles from Piyush Sinha?

Support the author by donating an amount of your choice.

Recent sponsors
Share this