gitdb-database

🗂️ GitDB: Essential Guide & SDK Reference

Production-ready NoSQL database that stores data in Git repositories with advanced features like GraphQL, AI-powered queries, version control, and performance optimizations.

🚀 Quick Links

SDK / Language	Docs / Repo	Package Registry
JavaScript/TS	gitdb-client (npm)	Docs
Go	gitdb-go-client (GitHub)	GoDoc
PHP	gitdb-php-client (GitHub)	Packagist
Rust	gitdb-client (crates.io)	Docs
Python	gitdb-client (PyPI)	Docs
Ruby	gitdb-client (RubyGems)	Docs

📝 GitDB CLI Command Table

Command	Usage & Options	Description
Connect	gitdb connect -t <token> -o <owner> -r <repo>	Connect CLI to a GitHub repo as your database
List Collections	gitdb collections	List all collections (tables)
Create Collection	gitdb create-collection <name>	Create a new collection
Delete Collection	gitdb delete-collection <name>	Delete a collection and all its documents
List Documents	gitdb documents <collection>	List all documents in a collection
Create Document	gitdb create-doc <collection> <json-data>	Add a new document to a collection
Read Document	gitdb read-doc <collection> <id>	Read a document by its ID
Update Document	gitdb update-doc <collection> <id> <json-data>	Update a document by its ID
Delete Document	gitdb delete-doc <collection> <id>	Delete a document by its ID
Find Documents	gitdb find <collection> <query>	Find documents matching a MongoDB-style query
Find One Document	gitdb findone <collection> <query>	Find a single document matching the query
Version History	gitdb version history <collection>	Show Git commit history for a collection
Rollback Version	gitdb version rollback <collection> --commit <hash>	Roll back a collection to a previous commit
Start Server	gitdb server	Start the GitDB server (REST/GraphQL API)
Start Server (bg)	gitdb server-start	Start the server in the background
Stop Server	gitdb server-stop	Stop the server
Server Status	gitdb server-status	Check the server status
Enable SuperMode	gitdb supermode enable --cache-size <n>	Enable performance optimizations
Show GraphQL Schema	gitdb graphql schema	Show the current GraphQL schema
Interactive Shell	gitdb shell	Start an interactive shell for running commands
Shell: Set Token	set token <token>	Set GitHub token (in shell)
Shell: Set Owner	set owner <owner>	Set repository owner (in shell)
Shell: Set Repo	set repo <repo>	Set repository name (in shell)
Shell: Use Collection	use <collection>	Switch to a collection (in shell)
Shell: Show Collections	show collections	List all collections (in shell)
Shell: Show Docs	show docs	List documents in current collection (in shell)
Shell: Insert	insert <JSON>	Insert a document (in shell)
Shell: Find by ID	find <id>	Find document by ID (in shell)
Shell: Find by Query	findone <json-query>	Find document by query (in shell)
Shell: Count	count [json-query]	Count documents (optionally by query, in shell)
Shell: Update	update <id> <JSON>	Update document by ID (in shell)
Shell: Delete	delete <id>	Delete document by ID (in shell)
Shell: Help	help	Show help (in shell)
Shell: Exit	exit	Exit the shell

🏁 Getting Started

• Create a GitHub repo for your data.
• Generate a GitHub token with repo permissions.
• Install the CLI:

npm install -g gitdb-database

• Connect:

   gitdb connect -t <token> -o <owner> -r <repo>

🗂️ GitDB Command Reference & Workflow Guide

1. GitDB CLI: Core Commands

Database Connection & Setup

• gitdb connect -t <token> -o <owner> -r <repo>
  • Connects your CLI to a GitHub repository as your database.
  • Example:
    gitdb connect -t ghp_abc123 -o myuser -r mydb-repo

Collection Management

• gitdb collections — List all collections
• gitdb create-collection <name> — Create a new collection
• gitdb delete-collection <name> — Delete a collection

Document Operations

• gitdb documents <collection> — List all documents in a collection
• gitdb create-doc <collection> <json-data> — Add a new document
• gitdb read-doc <collection> <id> — Read a document by ID
• gitdb update-doc <collection> <id> <json-data> — Update a document
• gitdb delete-doc <collection> <id> — Delete a document by ID

Querying

• gitdb find <collection> <query> — Find documents matching a MongoDB-style query
• gitdb findone <collection> <query> — Find a single document matching the query

Version Control & History

• gitdb version history <collection> — Show Git commit history for a collection
• gitdb version rollback <collection> --commit <hash> — Roll back a collection to a previous commit

Server Management

• gitdb server — Start the GitDB server (REST/GraphQL API)
• gitdb server-start / gitdb server-stop / gitdb server-status — Manage the server process

Advanced Features

• gitdb supermode enable --cache-size <n> — Enable performance optimizations
• gitdb graphql schema — Show the current GraphQL schema
• gitdb shell — Start an interactive shell for running commands

2. Typical GitDB Workflow

A. Initial Setup

• Create a GitHub repo for your data.
• Generate a GitHub token with repo permissions.
• Connect using the CLI:

gitdb connect -t <token> -o <owner> -r <repo>

B. Creating Collections & Documents

• Create collections for your data types:

   gitdb create-collection users
   gitdb create-collection products

• Insert documents:

   gitdb create-doc users '{"name":"Alice","email":"[e-mail]"}'
   gitdb create-doc products '{"name":"Laptop","price":999.99}'

C. Querying & Updating Data

• Find users over 25:

  gitdb find users '{"age":{"$gt":25}}'

• Update a user:

  gitdb update-doc users <id> '{"email":"[e-mail]"}'
  

• Delete a product:

  gitdb delete-doc products <id>

D. Version Control

• View history:

  gitdb version history users
  

• Rollback:

  gitdb version rollback users --commit <hash>

E. Server/API Usage

• Start the server:

gitdb server

• Access REST API:
  http://localhost:7896/api/v1/collections/users
• Access GraphQL API:
  http://localhost:7896/graphql

3. Interactive Shell Commands

Inside gitdb shell, you can use:

• set token <token>
• set owner <owner>
• set repo <repo>
• use <collection>
• create-collection <name>
• show collections
• show docs
• insert <JSON>
• find <id>
• findone <json-query>
• count [json-query]
• update <id> <JSON>
• delete <id>
• help
• exit

4. SDK Usage Example (JavaScript/TypeScript)

import { GitDBClient } from 'gitdb-client';

const client = new GitDBClient({
  owner: 'your-github-username',
  repo: 'your-repo',
  token: 'your-github-token',
});

// Insert a document
await client.insert('users', { name: 'Alice', email: '[e-mail]' });

// Query documents
const users = await client.findOne('users', { name: 'Alice' });

// Update a document
await client.update('users', users[0].id, { age: 31 });

// Delete a document
await client.delete('users', users[0].id);

5. Where to Find More

• Full Book & Advanced Docs: GITDB-Guide.md (Full Book)
• SDK Docs: See links in the table above for each language
• API Reference: GITDB-COMPLETE-BOOK.md and server endpoints

If you want a deep-dive into any specific command, workflow, or integration, just ask!