📦 grud: GitHub as database

Apr 16, 2021 23:00 · 767 words · 4 minute read grud GitHub npm

Ever tried building an internal tool at a big enterprise and hit the wall when you need a simple database? That’s exactly why I built grud – a tiny JavaScript package that turns GitHub into your JSON database.

The Problem: Enterprise Tool Purgatory

Working as a consultant in big enterprises, I constantly run into this frustrating cycle. I want to build a quick internal tool – maybe a React app hosted on GitHub Pages. It’s perfect: easy to scaffold, deploy to a public URL, and I don’t need to raise tickets or wait for approvals.

But then I need to store some data. Suddenly, I’m stuck. I can’t use Firebase or MongoDB Atlas because they’re external third party services. The enterprise alternatives? Good luck getting those provisioned for your “non-revenue-generating” internal tool. You’ll lose your passion waiting in the ServiceNow approval saga.

Here’s the thing though – internal tools that save engineering hours should be just as valuable as revenue-generating products. But try explaining that to your manager.

The Solution: Your Database Lives in GitHub

So I thought, why not host the database where I’m already hosting the app? Enter grud – GitHub as your database.

It’s a simple concept: grud uses GitHub’s API to store JSON data in a repository file and gives you a clean CRUD interface to work with it. Think of it as a lightweight database that lives entirely within GitHub.

How It Works

Install grud:

npm install grud

Initialize with your GitHub repo:

const Grud = require("grud");

let config = {
  owner: "yourusername",
  repo: "my-data-repo",
  path: "db.json",
  personalAccessToken: "your-token",
};

let db = new Grud(config);

Now you can perform standard database operations:

Create records:

const newPost = {
  author: "Anees",
  title: "Building internal tools",
  body: "Sometimes you just need a simple database...",
};

const result = await db.save(newPost);

Read data:

// Get all posts
const allPosts = await db.find();

// Find specific post
const post = await db.find({ author: "Anees" });

Update records:

await db.update(
  { _id: "301b63faac384a31b3e785ebf40295e5" },
  { title: "Updated title" }
);

Delete records:

await db.deleteOne({ author: "Anees" });

Behind the scenes, grud automatically creates a JSON file in your repository and uses GitHub’s API to read/write data. Each record gets a unique _id, and you can query by any field.

When to Use grud (And When Not To)

Perfect for:

  • Internal tools and prototypes
  • Hackathon projects
  • Small datasets (think hundreds, not thousands of records)
  • Situations where you can’t provision traditional databases
  • Quick MVP development

Skip it for:

  • High-performance applications
  • Large datasets
  • Applications requiring real-time updates
  • Production systems with strict security requirements
  • Anything where multiple users might write simultaneously

The Trade-offs

Let’s be honest about the limitations. GitHub’s API has rate limits, so grud isn’t built for high-frequency operations. Performance will be slower than traditional databases. And if your JSON file gets too large, operations become sluggish.

But here’s what you get in return: zero infrastructure setup, no server costs, automatic version control of your data (it’s just commits!), and it works anywhere GitHub works – including enterprise GitHub instances.

Real-World Use Cases

I’ve used grud for:

  • A team dashboard that tracks project statuses
  • A simple CRM for tracking client interactions
  • Prototype applications that needed persistent data
  • Internal forms that collect and store team feedback

But the most impactful project was building a DevOps team portal at my company using Next.js and grud. The portal provides complete transparency across all DevOps projects – team members can see project statuses, update their daily progress, manage availability, and track work completed each day.

Here’s what makes it interesting from a security perspective: each team member uses their own Personal Access Token to update data, but these tokens are never stored on GitHub or any server. Instead, they’re encrypted and stored in the user’s browser local storage. This means:

  • No centralized token management
  • Each person controls their own access
  • Zero server-side credential storage
  • Complete audit trail since every update is tied to individual GitHub accounts

The transparency this created was quite impressive. Instead of status update meetings, everyone could see real-time project progress. DevOps Manager could spot bottlenecks instantly, and resource allocation became data-driven rather than guesswork.

Building this with traditional enterprise tools would have taken months of approvals and infrastructure setup. With grud, I had it running in a week.

Get Started

Check out grud at npmjs.com/package/grud. The full documentation and examples are on GitHub.

If you’re tired of over-engineering simple data storage needs or stuck in enterprise approval hell, grud might just be the pragmatic solution you need. Sometimes the best database is the one you already have access to.

tweet Share