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
Victoria Lo's photo

Hey Piyush! Nice article! I was reading it and I wondered if you got inspired from my HarperDB demo project I published on GitHub a week ago: github.com/victoria-lo/harperdb-demo

It was so similiar, from the app to the code as well. I got goosebumps, thinking it was a coincidence. Correct me if I'm wrong haha 😊

Show +2 replies
Victoria Lo's photo

I see Piyush Sinha, thanks a lot for the clarification 😊 I got inspired from Cassidy's video too and decided to make it Top Programming Blogs instead of Book Reviews.

Looks like our coincidence was the fact that we have the same app idea to apply what we learned haha 😊😊

P.S. Will link this article on my own version coming up! Cheers!

Piyush Sinha's photo

Victoria Lo, I went through your repo just now... You have better styling than mine πŸ˜…. Eagerly waiting for your version. β™₯️

Victor Ikechukwu's photo

Great Article!, Now I can dive into using harperDB for the hashnode hackathon. Thanks for sharing Piyush Sinha!

Piyush Sinha's photo

Thanks Victor 😊. All the best for the hackathon πŸ†.

Savio Martin's photo

Great Article! Great work Piyush Sinha!

Piyush Sinha's photo

Thanks Savio. Glad you liked it!

Rutik Wankhade's photo

I was about to dive into harperDB and this post has really made it easy to understand. Thanks for sharing Piyush. πŸ™Œ This helps.

Piyush Sinha's photo

Happy to help. All the best for the hackathon πŸ†.

Catalin Pit's photo

Nice one! Thank you for the mention, Piyush Sinha! πŸ”₯

Piyush Sinha's photo

Thanks Catalin. Glad you liked it!

Mr.Unity Buddy's photo

Yay! Now I get about HarperDB😊😊. Thanks a lot for this article!

Piyush Sinha's photo

Thanks mate 😊. Glad you liked it!

Amolo's photo

Great article. However is it a good practice to put the username and password on the frontend. Can you also clarify this Victoria Lo ??

Victoria Lo's photo

Very excellent question Amolo! As you know, storing anything on the client is never 100% secure. For quick development and testing, the steps shown in this article would suffice. In actual production, always store important credentials and API keys in server-side.

Here's a helpful article that discusses on this topic.