gitnix 1.1.0

Use GitHub repos as an encrypted, high-performance database

Gitnix

Turn any GitHub repository into a fast, encrypted, zero-knowledge database.

Gitnix is a Python SDK that uses GitHub repos as a database backend. All data is end-to-end encrypted client-side — GitHub never sees your plaintext data.

Install

pip install gitnix

Quick Start

import os
from gitnix import Gitnix
from gitnix.types import GitnixConfig

db = Gitnix(GitnixConfig(
    repo="your-username/my-database",
    token=os.environ["GITHUB_TOKEN"],
    password="my-secret-encryption-key",
))

async with db:
    users = db.collection("users")

    # Insert
    await users.insert({"name": "Alice", "age": 30, "email": "[e-mail]"})

    # Query (MongoDB-style)
    adults = await users.find({"age": {"$gte": 18}})

    # Update
    await users.update({"name": "Alice"}, {"$set": {"age": 31}})

    # Delete
    await users.delete({"name": "Alice"})

    # Sync encrypted data to GitHub
    await db.sync()

Features

• Zero-Knowledge Encryption — XSalsa20-Poly1305 + Argon2id key derivation
• MongoDB-Style Queries — $eq, $gt, $in, $or, $regex, $contains, and more
• Sub-millisecond Operations — Local-first with encrypted disk cache
• GitHub Sync — On-demand push/pull to GitHub (encrypted blobs only)
• Binary/Image Storage — Chunked upload/download with MIME detection
• Transactions — Optimistic locking with conflict detection
• Async-Native — Built on asyncio with full async/await support
• Fully Typed — Complete type annotations, strict mypy compatible
• Rate Limit Aware — Built-in rate limiter with queue and backpressure

Performance

Operation	Avg Latency	Throughput
Create record	1.2ms	813 req/s
Read single	0.98ms	1,021 req/s
List all (50 docs)	1.0ms	995 req/s
Filtered query	0.65ms	1,531 req/s
Update record	1.0ms	1,000 req/s
Delete (+ cascade)	0.66ms	1,526 req/s
Push to GitHub	~3.0s	6 API calls
Pull from GitHub	~1.2s	3 API calls

Security

Property	Implementation
Algorithm	XSalsa20-Poly1305 (256-bit key)
Key derivation	Argon2id (memory-hard, GPU-resistant)
Per-record nonces	Random 24-byte nonce per encryption
Filename obfuscation	SHA-256 hashed names
Zero plaintext	GitHub only receives encrypted blobs

Security audit: A+ (49/49 tests passed across 11 categories)

Who Should Use This?

✅ Solo developers, side projects, MVPs, hackathons, privacy-focused apps, students, note-taking apps, config management, small teams (< 10), IoT/edge devices.

❌ Not for: high-traffic production (1000+ concurrent users), real-time apps, complex SQL joins, high-frequency writes (100+/sec), or data > 100GB.

Query Operators

# Comparison
await users.find({"age": {"$gt": 18}})
await users.find({"status": {"$in": ["active", "pending"]}})

# Logical
await users.find({"$or": [{"city": "NYC"}, {"city": "LA"}]})

# String
await users.find({"name": {"$contains": "alice"}})
await users.find({"email": {"$regex": "^admin@"}})

# Options
await users.find(query, sort={"age": -1}, skip=0, limit=20)

Also Available

• JavaScript/TypeScript SDK: npm install gitnix — npm
• Full Example App: Event registration platform with admin panel, auth, and 45 E2E tests

Documentation

• GitHub Repository
• JavaScript API Reference
• Python API Reference
• Security & Threat Model
• Usage Guide & Examples
• Architecture Deep Dive
• Example App (Event Registration)
• npm (JavaScript SDK)

License

MIT — Quilonix