shadeDB

♟️ Mission

🚀 shadeDB, also know as shadecrypt, is a lightweight, multipurpose CLI + Python database server — small enough to run anywhere, yet powerful enough to manage structured data with speed and simplicity.

Unlike traditional file-based CLIs, shadeDB works more like Redis:

• You initialize once → a background server process holds the live database in memory.
• All future CLI commands (put, get, update, etc.) talk to that server via a local socket.
• The server automatically persists data to a .scdb file, with optional write and backup controls.

---

✨ Features

• Class-oriented design — core database logic is in the shadeDB class.
• Persistent workflow — one live server handles all operations.
• Background persistence — in-memory with disk persistence.
• Portable — runs on Linux, macOS, Windows, Android (via Termux).
• Multipurpose CLI — simple commands: init, start, use, pull, get, update, remove, ls, stop.
• Config-aware — automatically tracks the “current” DB in ~/.shadeDB/config.scdb.

---

🔧 Installation

pip install shadeDB

After install, the shadeDB command is available globally. A shorter keyword for shadeDB - scdb

---

⚡ Quickstart (CLI)

1. Initialize a database

Creates ./mydb.scdb, starts the server, and sets it as default:

shadeDB init ./mydb.scdb backup

⚠️ Only provide the "backup" argument if you intend for the server to register newer backups as you make new changes.

2. Start database server

This is necessary, as the cli wrapper only communicates with the database server to retrieve,update,remove and store data.

shadeDB start

---

3. Insert data

shadeDB update alice.age 17 && scdb update alice.gender female

---

4. Fetch data

shadeDB get alice
# {"nickname": "Shade", "status": "active"}

---

5. Nested access

shadeDB pull alice.nickname
# "Shade"

---

Making single value updates, it is compulsory to surround with double quotes.

6. Update

shadeDB update alice "my name is alice"

---

7. Remove

shadeDB remove alice 
# deletes {"nickname":"shade","status":"active"}

8. Remove nested

shadeDB remove alice.nickname
# deletes {"nickname":"shade"} 

---

9. Check for the current database

shadeDB ls
# ./mysql.scsb

---

10. Switch database

shadeDB use ./backup.scdb backup
# Only provide the backup argument, if it need arises.

---

11. Stop server

shadeDB stop

---

📚 Python API

shadeDB can also be embedded directly into Python apps using the shadeDB class.

🔧 Initialize

from shadeDB.core import shadeDB

db = shadeDB(
    file="./data.scdb",
    write=True,
    id=True,
    backup=False,
    silent=False
)

Parameters

• file (str) → Path to .scdb file
• write (bool) → Persist changes to disk (default: True)
• id (bool) → Assign unique ID per entry (default: True)
• backup (bool) → Keep backup copy (default: False)
• silent (bool) → Whether to display a welcome message via cli on the disk's first initialisation

---

🛠️ Key Methods

db.update(("alice", {"nickname": "Shade", "status": "active"}))   # Insert/update
db.get("alice", multiple=True/False)      # Fetch record
db.get("alice.nickname")  # Fetch nested value
db.get_context("alice")   # Get full dict
db.get_by_id(1) # Fetch by ID
db.get_id("alice",multiple=True/False) # Get ID of key
db.items()                # List all entries
db.import_dict({...},overwrite=True/False)     # Import dictionary, can also overwrite existing records
db.export_dict()          # Export to dictionary
db.remove("alice")        # Delete entry
db.clear()                # Clear all
db.status()               # DB status
db.__performance__()      # Performance stats

---

⚡ Example Workflow

from shadeDB.core import shadeDB

db = shadeDB("./appdata.scdb", write=True)

# Insert
db.update(("alice", {"nickname": "Shade", "status": "active"}))

# Nested access
print(db.get("alice.nickname"))   # Shade

# Full context
print(db.get_context("alice"))    # {'nickname': 'Shade', 'status': 'active'}

# Export
print(db.export_dict())

---

📑 Command & Method Reference

Command / Method	Description
init <file> <backup>	Initialize DB + server
use <file> <backup>	Switch database
pull <key>.<value>	Fetch nested record
get <key>	Fetch data
update <key>.<value>	Update existing record
remove <key>	Delete entry ( Supports dot notation)
ls	Current database
stop	Stop server
update(item)	Insert/update via Python
get(key,multiple=True/False)	Fetch record
get_context(key)	Full dictionary view
get_by_id(id)	Fetch by unique ID
get_id(key,multiple=True/False)	Return ID of key
items()	List all entries
import_dict(dict,overwrite=True/False)	Import bulk dict
export_dict()	Export full dict
remove(key)	Delete by key/ID
clear()	Wipe database
status()	DB status info
__performance__()	Compile time & stats

🔮 Few hints on what's to come in future updates

• Remote mode → optional TCP listener so shadeDB can be queried from another device (like Redis-lite networking).
• Replication/Sync → lightweight push/pull sync between devices.
• Faster query returns → implement a new algorithm to speed up query processing.
• Custom encryption algorithm → device based encryption algorithm.
• Plugin system → user-defined operations via Python modules.