HarperDB – First Impressions

Reading Time: 2 minutes

I saw a post on LinkedIn about a platform called HarperDB.

It’s billed as a distributed database, cache, and pub/sub engine rolled into one. That sounded interesting enough to try out.

HarperDB is a single-system platform that combines a SQL-like API, REST endpoints, and MQTT messaging on top of a document-style data model. It runs locally or in the cloud, and the setup takes less than a minute.


For CLI installation instructions, see HarperDB’s Install Guide.<
For web access via the Studio UI, go to http://localhost:9926 once HarperDB is running locally.

Here’s what I did:

Setting Up Node.js

Before anything else, I made sure Node.js and npm were installed. On macOS, you can check by running:

node -v
npm -v

If either command fails, you can install both with Homebrew:

brew install node

Once that’s done, I created a new project directory and initialized it:

mkdir harper-demo
cd harper-demo
npm init -y

Then I installed Express:

npm install express

And created a simple index.js file as the entry point. Just enough to spin up a server and test connectivity.

First Impressions

Harper has a free tier and a CLI you can install globally via npm. Running ‘npm install -g harperdb’ threw a couple of deprecation warnings (lodash.get, json2csv), which I made a note of. Nothing that blocked progress.

From there, running harperdb kicks off an install wizard. You pick a directory, set a username and password, choose dev or prod mode, and it spins up a local instance. It was up and running in under a minute.

I pointed my browser to http://localhost:9926 and landed in HarperDB Studio — a clean web UI for managing schemas, tables, and records. I created a schema called harper_demo, added a table called tasks, and used id as the hash attribute (basically the primary key).

Writing a Simple App

To test the API, I scaffolded a basic Node.js app using Express. I installed axios and built two endpoints: one to insert tasks and one to list them.

app.post('/add', async (req, res) => {
const data = req.body;

const response = await axios.post(HARPERDB_URL, {
operation: 'insert',
schema: 'harper_demo',
table: 'tasks',
records: [data],
}, { auth: HARPERDB_AUTH });

res.json(response.data);
});

You can find the complete, yet basic code here:
https://github.com/jimoconnell/harper-demo

I used the REST Client plugin in VS Code to hit the /add and /list routes. After correcting a few early mistakes — wrong schema name, missing fields — everything clicked into place.

Thoughts So Far

The install experience was surprisingly smooth. I like that it runs locally without needing Docker or external services. The API is simple. And having MQTT, REST, and SQL-style queries all exposed from the same backend is unusual in a good way.

From deciding to explore HarperDB until having the working minimal app running took about an hour. That’s impressive.

I haven’t touched the pub/sub or custom functions yet, but the foundation looks solid. I’ll probably try pushing live data into it next — maybe simulate IoT readings or wire up a frontend.

More soon.

Leave a Reply