Using GitHub as a Free Database

Your database just became a git repository.

---

What if your database was also your version control? Every change tracked. Every value recoverable. Free hosting. Zero setup.

That's keyv-github - a storage adapter that uses GitHub repositories as key-value stores.

Why GitHub?

Consider what GitHub already provides:

• Free hosting - unlimited public repos, generous private limits
• Built-in versioning - every change is a commit
• Global CDN - raw file access via jsDelivr
• API access - 5,000 requests/hour authenticated
• Web UI - browse your data in the browser

For certain use cases, this is better than any managed database.

The Problem with Traditional Options

Self-Hosted Databases

Require servers, maintenance, backups, security updates. Too much overhead for a simple script or prototype.

Cloud Databases

Monthly fees add up. Cold start latency. Vendor lock-in. Configuration complexity.

Local Files

Not accessible remotely. No collaboration. No version history.

The Solution: keyv-github

import Keyv from "keyv";
import KeyvGithub from "keyv-github";

const store = new KeyvGithub("owner/repo/tree/main", {
  client: new Octokit({ auth: process.env.GITHUB_TOKEN })
});

const kv = new Keyv({ store });

// Your GitHub repo is now a database
await kv.set("config/settings.json", { theme: "dark" });
await kv.get("config/settings.json"); // { theme: "dark" }

Each key becomes a file. Each value becomes file content. Your repo structure is your data structure.

How It Works

File-Based Storage

your-repo/
├── users/
│   ├── alice.json
│   └── bob.json
├── config/
│   └── settings.json
└── cache/
    └── api-response.json

Keys map directly to file paths:

await kv.set("users/alice.json", { name: "Alice", role: "admin" });
// Creates: your-repo/users/alice.json

API Operations

Operation	API Calls	Description
get	1	Fetch file contents
set	2	Read SHA + create/update file
delete	2	Read SHA + delete file
has	1	Check file existence

Commit Trail

Every write creates a commit:

chore: update users/alice.json
chore: delete cache/old-data.json

Full audit trail. Rollback any time. Blame for every change.

Rate Limits: The Reality Check

GitHub API has limits:

• Unauthenticated: 60 requests/hour
• Authenticated: 5,000 requests/hour

For a simple CRUD app doing 10 ops/minute, that's 600/hour. Well within limits.

But for high-frequency access, you need caching.

Multi-Layer Caching

The real power comes from combining stores:

import KeyvNest from "keyv-nest";
import { KeyvDirStore } from "keyv-dir-store";
import KeyvGithub from "keyv-github";

const store = KeyvNest(
  memoryStore,                  // L1: Memory (instant)
  new KeyvDirStore("./cache"),  // L2: Local disk (fast)
  new KeyvGithub("owner/repo")  // L3: GitHub (persistent)
);

Read Flow

1. Check memory → miss
2. Check local disk → miss
3. Fetch from GitHub → hit
4. Backfill to disk and memory
5. Future reads hit memory

Write Flow

1. Write to memory
2. Write to disk
3. Write to GitHub (async)
4. Consistent across all layers

With this setup, GitHub is only touched on cold starts or when data changes.

Real-World Use Cases

Configuration Management

// Centralized config that's version-controlled
const config = await kv.get("services/api/config.json");

// Update config (creates commit with history)
await kv.set("services/api/config.json", {
  ...config,
  maxRetries: 5
});

Static Site Data

// Blog CMS without a database
await kv.set("posts/hello-world.json", {
  title: "Hello World",
  content: "...",
  publishedAt: new Date().toISOString()
});

// Build script reads directly from GitHub
const posts = await kv.get("posts/index.json");

Lightweight APIs

// Serverless API backed by GitHub
export async function GET(request: Request) {
  const { id } = parseParams(request);
  const user = await kv.get(`users/${id}.json`);
  return Response.json(user);
}

Distributed Caching

// Share cache across CI runners
const cache = new KeyvGithub("org/ci-cache");

// Save build artifacts
await cache.set("builds/latest.json", buildMetadata);

// Other runners read cached data
const cached = await cache.get("builds/latest.json");

Constructor Options

new KeyvGithub(repoUrl, {
  branch: "main",           // Target branch
  client: new Octokit(),    // Authenticated client
  prefix: "data/",          // Path prefix for all keys
  suffix: ".json",          // File extension
  msg: (key, val) => "...", // Custom commit messages
});

Path Prefixes

Keep your data organized:

const store = new KeyvGithub("owner/repo", {
  prefix: "data/v1/",
  suffix: ".json"
});

await store.set("users/alice", data);
// Writes to: data/v1/users/alice.json

Custom Commit Messages

const store = new KeyvGithub("owner/repo", {
  msg: (key, value) =>
    value === null
      ? `feat: remove ${key}`
      : `feat: update ${key}`
});

Key Validation

Keys must be valid file paths:

// ✓ Valid
await store.set("config/settings.json", data);
await store.set("users/alice/profile.json", data);

// ✗ Invalid - throws error
await store.set("/absolute/path", data);      // leading slash
await store.set("../escape/attempt", data);   // directory traversal
await store.set("path//double", data);        // double slashes

Comparison

Feature	keyv-github	Redis	SQLite	MongoDB Atlas
Cost	Free	$$$	Local only	$$
Setup	Zero	Config needed	File setup	Cloud setup
Version control	Built-in	None	None	None
Remote access	Yes	Yes	No	Yes
Query language	Key-based	Key-based	SQL	MongoDB QL
Best for	Config, small data	High-speed cache	Local apps	Complex queries

When NOT to Use

• High-frequency writes - Too many API calls
• Large datasets - GitHub has file size limits
• Real-time requirements - API latency is 100-500ms
• Complex queries - Key-value only, no filtering
• Sensitive data - Unless repo is private and secured

When to Use

• Configuration storage - Version-controlled settings
• Prototype backends - Zero infrastructure
• Static site data - CMS without a database
• CI/CD artifacts - Shared build cache
• Personal projects - Free, persistent storage

Installation

npm install keyv-github

import Keyv from "keyv";
import KeyvGithub from "keyv-github";

const kv = new Keyv({
  store: new KeyvGithub("you/your-repo", {
    client: new Octokit({ auth: process.env.GITHUB_TOKEN })
  })
});

// You now have a free, version-controlled database
await kv.set("hello", "world");

---

Try It

Install: npm install keyv-github

GitHub: github.com/snomiao/keyv-github

Related: keyv-nest for multi-layer caching

---

Snowstar Miao builds infrastructure tools that question conventional architecture.