GaaD - Git as a Database

The most over-engineered database solution you never knew you needed.

Why use boring SQL when you can have IMMUTABLE, DISTRIBUTED storage?

Installation • Quick Start • API Documentation • FAQ • Contributing

🎯 What is GaaD?

GaaD (Git as a Database) is a revolutionary database engine that leverages Git commit history as a storage layer. Because when you think "high-performance data storage," you naturally think "version control system designed for source code."

Why GaaD?

Traditional databases are so 1970s. Here's why GaaD is the future:

| Feature | Traditional DB | GaaD | | ---------------------- | ---------------------- | ------------------------------ | | ACID Compliance | ✅ Yes | ❓ What's that? | | Indexing | ✅ B-Trees, Hash | ❌ Full table scan only | | Query Optimization | ✅ Advanced | ❌ Moore's Law will handle it | | Joins | ✅ Supported | ❌ Just denormalize everything | | Transactions | ✅ MVCC | ✅ Every insert is a commit! | | Backup | 🔧 Complex tools | ✅ git push | | Scalability | 📈 Vertical/Horizontal | 📈 Just add more commits | | Blockchain Ready | ❌ No | ✅ Absolutely! |

🚀 Features

• 🔒 Immutable by Design: Data never gets deleted, just like your production bugs
• 📦 Distributed Out of the Box: git clone your entire database to any machine
• ⛓️ Blockchain Compatible: SHA-1 hashes = basically cryptocurrency
• 🌐 Web Scale: O(n) complexity on every read operation means infinite scalability*
• 🎯 Zero Configuration: Auto-initializes Git repo if not found
• 🤝 Cross-Platform: Works on Windows, macOS, and Linux (equally poorly)
• 💾 Simple Backups: Just git push to GitHub (free hosting!)
• 🔍 Advanced Querying: Supports SELECT * (that's it, that's all you need)
• 🌟 Type-Safe: Full TypeScript support

* Scalability claims not verified by any credible source

📦 Installation

npm install gaad
# or
yarn add gaad

Requirements:

• Node.js >= 10
• Git (obviously)
• A sense of humor
• Low performance expectations

🏃 Quick Start

import { GitDB } from 'gaad';

// Initialize your "database cluster"
const db = new GitDB();

// INSERT - Create an immutable record in the blockchain (Git history)
db.insert('users', {
  name: 'Linus Torvalds',
  email: '[email protected]',
  role: 'Git Lord',
  favoriteDatabase: 'Definitely not this one',
});

// SELECT - Full table scan every time!
const users = db.select('users');
console.log(`Found ${users.records.length} users`);

// DROP TABLE - Data still exists, we just promise not to look
db.dropTable('users');

// Get impressive metrics for your manager
const stats = db.getStats();
console.log(`Web Scale Level: ${stats.webScaleLevel}`);

📚 API Documentation

new GitDB(repoPath?: string)

Initialize a new GitDB instance. If the repository doesn't exist, we'll create it for you because we're thoughtful like that.

const db = new GitDB(); // Uses current directory
const db2 = new GitDB('/path/to/repo'); // Custom path

Note: The constructor will automatically run git init if no repository exists. This is "CREATE DATABASE IF NOT EXISTS" but cooler.

insert(tableName: string, data: GitDBRecord): InsertResult

Insert a record into a "table" (really just a tag in commit messages).

Example:

const result = db.insert('products', {
  name: 'Web Scale Sticker',
  price: 9.99,
  inStock: true,
});

console.log(result.commitHash); // Your "primary key"

Performance Characteristics:

• Time Complexity: O(1) ✅
• Space Complexity: O(1) ✅
• Your Repo Size: O(n) ⚠️

select(tableName: string): SelectResult

Retrieve all records from a "table". Performs a full git log scan every time.

Example:

const products = db.select('products');
products.records.forEach(product => {
  console.log(`${product.name}: $${product.price}`);
});

Performance Characteristics:

• Time Complexity: O(n) where n = total commits
• Space Complexity: O(n)
• Developer Sanity: O(0)
• Alternative: Use a real database

dropTable(tableName: string): string

"Delete" a table by creating a tombstone commit. Data remains in history because immutability.

Example:

const tombstoneHash = db.dropTable('old_users');
// Data still exists in git history, we just pinky promise not to read it

Original Implementation: Was going to run rm -rf .git, but lawyers said no.

getStats(): Record<string, string | number>

Get database statistics to impress your manager.

Returns:

{
  totalCommits: 42,
  repoSize: '2.1 MiB',
  firstCommitHash: 'a1b2c3d',
  latestCommitHash: 'x9y8z7w',
  webScaleLevel: 'MAXIMUM', // or 'HIGH' or 'GROWING'
  blockchainNodes: 1,
  caffeineRequired: 'Infinite'
}

getBackupInstructions(): string

Get instructions for backing up your database (spoiler: it's git push).

🎓 Advanced Usage

Migrations

// Migration strategy: Don't.
// Just insert new data with a different schema.
// It's called "schema evolution" and it's a feature.

Replication

// Master-Slave Replication:
// 1. git push origin master
// 2. (on slave) git pull origin master
//
// Multi-Master Replication:
// Deal with merge conflicts like a real engineer

Indexing

// Indexes? Where we're going, we don't need indexes.
// Every query is a full table scan.
// This builds character.

Transactions

// Each insert is already a transaction!
// Atomic? Yes. ✅
// Consistent? Probably. ✅
// Isolated? Sure, why not. ✅
// Durable? It's in Git! ✅

🏗️ Architecture

┌─────────────────────────────────────────────┐
│           Application Layer                  │
│  (Your Beautiful TypeScript Code)           │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│              GitDB Class                     │
│  • insert() ──► git commit --allow-empty    │
│  • select() ──► git log --grep              │
│  • drop()   ──► git commit (tombstone)      │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│          Git Storage Engine                  │
│  (SHA-1 Hashes = Blockchain Technology™)    │
└─────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│           Your File System                   │
│  (The Real Database)                         │
└─────────────────────────────────────────────┘

📊 Benchmarks

We don't have any benchmarks because:

1. We didn't run any tests
2. The results would be depressing
3. Ignorance is bliss

But here's what we imagine:

| Operation | GaaD | PostgreSQL | MongoDB | | ------------------ | ---------------- | ---------- | ------- | | Insert | ~10ms | ~1ms | ~2ms | | Select (1 row) | ~500ms* | ~0.1ms | ~1ms | | Select (1000 rows) | ~5000ms* | ~10ms | ~50ms | | Join | ❌ Not supported | ~5ms | ~20ms | | Index lookup | ❌ No indexes | ~0.01ms | ~1ms |

* Times increase linearly with total commit count

❓ FAQ

Q: Is this production-ready?

A: Define "production." If your production is a hobby blog with 2 visitors per month, maybe. Otherwise, absolutely not.

Q: How do I do JOINs?

A: You don't. Denormalize everything and embrace the chaos.

Q: What about query optimization?

A: We have a saying: "O(n) today, O(n) tomorrow, O(n) forever."

Q: Can I use this for my startup?

A: Only if you want your startup to fail spectacularly and become a cautionary tale.

Q: How do I handle concurrent writes?

A: Git merge conflicts! It's distributed computing™ in action.

Q: What's the maximum database size?

A: Technically unlimited! Practically limited by your SSD and patience.

Q: Why did you build this?

A: Science isn't about WHY, it's about WHY NOT!

Q: Should I actually use this?

A:

🐛 Known Issues

• ✅ Performance degrades linearly with commit count (This is a feature)
• ✅ No support for complex queries (Just iterate in JavaScript!)
• ✅ Concurrent writes may cause merge conflicts (Distributed consensus!)
• ✅ Repo size grows infinitely (Storage is cheap!)
• ✅ No indexes (Full table scans build character!)
• ✅ Can't actually delete data (True immutability!)

🤝 Contributing

We welcome contributions! Especially:

• Performance improvements (desperately needed)
• Test coverage (currently 0%)
• Documentation for features that probably shouldn't exist
• Therapy recommendations for the maintainer

Please don't:

• Use this in production
• Recommend this to anyone
• Take this seriously

📜 License

MIT License - Because even jokes need legal protection.

🙏 Acknowledgments

• Linus Torvalds - For creating Git (sorry for this)
• MongoDB - For showing us that databases don't need schemas
• Blockchain - For proving people will believe anything is revolutionary
• Every MongoDB is Web Scale video - For inspiration

⚠️ Disclaimer

This project is a parody and should not be used for any serious application. The author is not responsible for:

• Data loss
• Performance issues
• Angry managers
• Existential crises
• Getting fired
• Your repository becoming larger than your actual data
• Questions about your sanity

If you're actually considering using this in production, please seek help from:

1. A database expert
2. A senior engineer
3. A therapist
4. All of the above

🔗 See Also

• MongoDB is Web Scale - Our spiritual predecessor
• FizzBuzz Enterprise Edition - Similar energy
• SQLite - An actual good database you should use instead

Remember: If it's stupid but it works, it's still stupid.

Made with 😤 by someone who has spent too much time with Git