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.
One Reply to “HarperDB – First Impressions”