GitDB - Production-Ready GitHub-Backed NoSQL Database
A production-ready CLI tool and API server for managing a NoSQL database using GitHub repositories as storage. Features both command-line interface and REST API with interactive shell.
π Quick Start (Production)
1. Build for Production
npm run build:prod
2. Create Installers (All Platforms)
npm run build:installers
3. Install GitDB
Windows
GitDB-2.0.0-x64.msi
GitDB-2.0.0-x86.msi
GitDB-Setup-v2.0.0.exe
install-gitdb-windows.bat
macOS
chmod +x install-gitdb-macos.sh
./install-gitdb-macos.sh
Linux
chmod +x install-gitdb-linux.sh
./install-gitdb-linux.sh
4. Start Using GitDB
Start API Server
gitdb-server.exe
gitdb-server
Use Interactive Shell
gitdb-shell.exe
gitdb-shell
Use CLI
gitdb-cli.exe --help
gitdb-cli --help
π¦ Available Installers
Windows
- GitDB-2.0.0-x64.msi - Professional MSI installer (64-bit) [RECOMMENDED]
- GitDB-2.0.0-x86.msi - Professional MSI installer (32-bit)
- GitDB-Setup-v2.0.0.exe - NSIS installer with PATH integration
- GitDB-Windows-v2.0.0.zip - Portable package
- install-gitdb-windows.bat - Batch installer
macOS
- GitDB-macOS-v2.0.0.zip - Portable package with installer script
- install-gitdb-macos.sh - Shell installer
Linux
- GitDB-Linux-v2.0.0.zip - Portable package with installer script
- install-gitdb-linux.sh - Shell installer
Universal
- GitDB-Universal-v2.0.0.zip - Cross-platform package
- GitDB-Portable-v2.0.0.zip - Complete portable package
π Interactive Shell
Start the interactive shell for database operations:
gitdb-shell
Shell Commands
π Connection:
connect <token> <owner> <repo> Connect to database
disconnect Disconnect from database
status Show connection status
π Collections:
collections List all collections
create-collection <name> Create a new collection
delete-collection <name> Delete a collection
use <collection> Set current collection
π Documents:
docs List documents in current collection
insert <json> Insert a new document
find <id> Find document by ID
update <id> <json> Update document by ID
delete <id> Delete document by ID
π οΈ Utility:
clear Clear screen
help Show this help
exit, quit Exit shell
Example Shell Session
π GitDB Shell - GitHub-backed NoSQL Database
gitdb> connect your_token your_username your_repo
β
Connected to database: your_username/your_repo
gitdb> create-collection users
β
Collection 'users' created successfully
gitdb> use users
π Using collection: users
gitdb> insert {"name":"Alice","email":"alice@example.com"}
β
Document created with ID: abc123def456
gitdb> find abc123def456
{
"_id": "abc123def456",
"name": "Alice",
"email": "alice@example.com",
"createdAt": "2024-01-01T12:00:00.000Z"
}
gitdb> update abc123def456 {"email":"alice@new.com"}
β
Document updated successfully
gitdb> docs
π Documents in 'users':
- abc123def456
gitdb> exit
π Goodbye!
π₯οΈ Command Line Interface
Use the CLI for scripting and automation:
gitdb-cli --help
CLI Commands
gitdb-cli connect -t <token> -o <owner> -r <repo>
gitdb-cli collections
gitdb-cli create-collection <name>
gitdb-cli delete-collection <name>
gitdb-cli documents <collection>
gitdb-cli create-doc <collection> '{"name":"John","email":"john@example.com"}'
gitdb-cli read-doc <collection> <id>
gitdb-cli update-doc <collection> <id> '{"email":"john@new.com"}'
gitdb-cli delete-doc <collection> <id>
gitdb-cli find <collection> '{"name":"John"}'
gitdb-cli status
π REST API
The API server provides RESTful endpoints for database operations.
Start API Server
gitdb-server
The server will start on port 7896 by default.
Base URL
http://localhost:7896/api/v1
Authentication
First, connect to a database:
POST /api/v1/collections/connect
Content-Type: application/json
{
"token": "your_github_token",
"owner": "your_username",
"repo": "your_repo"
}
Collection Endpoints
List Collections
GET /api/v1/collections
Create Collection
POST /api/v1/collections
Content-Type: application/json
{
"name": "users"
}
Delete Collection
DELETE /api/v1/collections/users
Get Collection Info
GET /api/v1/collections/users
Document Endpoints
List Documents
GET /api/v1/collections/users/documents
Create Document
POST /api/v1/collections/users/documents
Content-Type: application/json
{
"name": "Alice",
"email": "alice@example.com"
}
Get Document
GET /api/v1/collections/users/documents/abc123def456
Update Document
PUT /api/v1/collections/users/documents/abc123def456
Content-Type: application/json
{
"email": "alice@new.com"
}
Delete Document
DELETE /api/v1/collections/users/documents/abc123def456
Find Documents
POST /api/v1/collections/users/documents/find
Content-Type: application/json
{
"name": "Alice"
}
π Backend Integration Examples
Node.js (JavaScript/TypeScript)
Using Axios
const axios = require('axios');
class GitDBClient {
constructor(baseURL = 'http://localhost:7896/api/v1') {
this.baseURL = baseURL;
}
async connect(token, owner, repo) {
const response = await axios.post(`${this.baseURL}/collections/connect`, {
token, owner, repo
});
return response.data;
}
async createCollection(name) {
const response = await axios.post(`${this.baseURL}/collections`, { name });
return response.data;
}
async insertDocument(collection, data) {
const response = await axios.post(`${this.baseURL}/collections/${collection}/documents`, data);
return response.data;
}
async getDocument(collection, id) {
const response = await axios.get(`${this.baseURL}/collections/${collection}/documents/${id}`);
return response.data;
}
async updateDocument(collection, id, data) {
const response = await axios.put(`${this.baseURL}/collections/${collection}/documents/${id}`, data);
return response.data;
}
async deleteDocument(collection, id) {
const response = await axios.delete(`${this.baseURL}/collections/${collection}/documents/${id}`);
return response.data;
}
}
const gitdb = new GitDBClient();
await gitdb.connect('your_token', 'your_username', 'your_repo');
await gitdb.createCollection('users');
await gitdb.insertDocument('users', { name: 'Alice', email: 'alice@example.com' });
Python
Using Requests
import requests
import json
class GitDBClient:
def __init__(self, base_url="http://localhost:7896/api/v1"):
self.base_url = base_url
self.session = requests.Session()
self.session.headers.update({'Content-Type': 'application/json'})
def connect(self, token, owner, repo):
response = self.session.post(f"{self.base_url}/collections/connect",
json={'token': token, 'owner': owner, 'repo': repo})
return response.json()
def create_collection(self, name):
response = self.session.post(f"{self.base_url}/collections", json={'name': name})
return response.json()
def insert_document(self, collection, data):
response = self.session.post(f"{self.base_url}/collections/{collection}/documents",
json=data)
return response.json()
def get_document(self, collection, doc_id):
response = self.session.get(f"{self.base_url}/collections/{collection}/documents/{doc_id}")
return response.json()
def update_document(self, collection, doc_id, data):
response = self.session.put(f"{self.base_url}/collections/{collection}/documents/{doc_id}",
json=data)
return response.json()
def delete_document(self, collection, doc_id):
response = self.session.delete(f"{self.base_url}/collections/{collection}/documents/{doc_id}")
return response.json()
gitdb = GitDBClient()
gitdb.connect('your_token', 'your_username', 'your_repo')
gitdb.create_collection('users')
gitdb.insert_document('users', {'name': 'Alice', 'email': 'alice@example.com'})
ποΈ Development
Project Structure
src/
βββ api/ # REST API routes
βββ core/ # Database manager and CRUD operations
βββ github/ # GitHub API integration
βββ models/ # Data models
βββ utils/ # Utility functions
βββ config/ # Configuration files
βββ cli.ts # Command-line interface
βββ shell.ts # Interactive shell
βββ server.ts # API server
Available Scripts
npm run build
- Build TypeScript to JavaScript
npm run build:prod
- Complete production build
npm run build:installers
- Build all installers
npm run dev
- Start development server with hot reload
npm run start
- Start production server
npm run shell
- Start interactive shell
npm run cli
- Run CLI commands
npm run clean
- Clean build directory
π Security
- GitHub tokens are only used for API calls and never stored permanently
- All operations are logged for audit purposes
- Connection state is maintained in memory only
- Production configuration includes rate limiting and security headers
π License
MIT
π Version 2.0.0 - Production Release
What's New
- β
Production-ready build system
- β
Cross-platform installers (Windows, macOS, Linux)
- β
Standalone executables
- β
Optimized TypeScript configuration
- β
Comprehensive installer scripts
- β
Portable packages
- β
Simplified installation process
Installation Packages
- Windows: NSIS installer, batch installer, portable ZIP
- macOS: Shell installer, portable ZIP
- Linux: Shell installer, portable ZIP
- Universal: Cross-platform package with all installers