{"id":31923518,"url":"https://github.com/harkerbyte/shadedb","last_synced_at":"2026-05-15T01:05:28.519Z","repository":{"id":316301175,"uuid":"1062622561","full_name":"harkerbyte/shadeDB","owner":"harkerbyte","description":"shadeDB, also know as shadecrypt is a lightweight instance and a database engine, small enough to run in any environment. Fast enough to return queries in milliseconds and smart enough to consistently offload in-memory datas to a persistent disk.","archived":false,"fork":false,"pushed_at":"2025-09-23T19:55:39.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-23T21:15:13.437Z","etag":null,"topics":["database","nosql","nosql-database","shadedb"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harkerbyte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T13:56:13.000Z","updated_at":"2025-09-23T19:55:43.000Z","dependencies_parsed_at":"2025-09-23T21:16:07.025Z","dependency_job_id":"5b53ea3e-ff5e-4683-9abe-a98716961073","html_url":"https://github.com/harkerbyte/shadeDB","commit_stats":null,"previous_names":["harkerbyte/shadedb"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/harkerbyte/shadeDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harkerbyte%2FshadeDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harkerbyte%2FshadeDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harkerbyte%2FshadeDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harkerbyte%2FshadeDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harkerbyte","download_url":"https://codeload.github.com/harkerbyte/shadeDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harkerbyte%2FshadeDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017194,"owners_count":26086017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","nosql","nosql-database","shadedb"],"created_at":"2025-10-13T23:55:01.572Z","updated_at":"2026-05-15T01:05:28.502Z","avatar_url":"https://github.com/harkerbyte.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shadeDB\n![PyPI - Version](https://img.shields.io/pypi/v/shadeDB?color=blue\u0026label=PyPI)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/shadeDB?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=BLUE\u0026left_text=downloads)](https://pepy.tech/projects/shadeDB)\n![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows%20%7C%20android-lightgrey)\n![License](https://img.shields.io/pypi/l/shadeDB?color=yellow)\n\u003ca href = \"https://facebook.com/harkerbyte\"\u003e![Facebook](https://img.shields.io/badge/Facebook-%231877F2.svg?style=flat\u0026logo=Facebook\u0026logoColor=white)\u003c/a\u003e\n\u003ca href =\"https://youtube.com/@harkerbyte?si=aPSIREosLJlFOmyX\" \u003e![YouTube](https://img.shields.io/badge/YouTube-%23FF0000.svg?style=flat\u0026logo=YouTube\u0026logoColor=white)\u003c/a\u003e\n\u003ca href=\"https://whatsapp.com/channel/0029Vb5f98Z90x2p6S1rhT0S\"\u003e![WhatsApp](https://img.shields.io/badge/WhatsApp-25D366?style=flat\u0026logo=whatsapp\u0026logoColor=white)\u003c/a\u003e\n\u003ca href=\"https://instagram.com/harkerbyte\" \u003e\n![Instagram](https://img.shields.io/badge/Instagram-E4405F?style=flat\u0026amp;logo=instagram\u0026amp;logoColor=white) \u003c/a\u003e\n\n\n[♟️ Mission](https://harkerbyte.github.io/portfolio/)\n\n\n🚀 **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.  \n\nUnlike traditional file-based CLIs, shadeDB works more like Redis:  \n\n- You **initialize once** → a background server process holds the live database in memory.  \n- All future CLI commands (`put`, `get`, `update`, etc.) talk to that server via a local socket.  \n- The server **automatically persists** data to a `.scdb` file, with optional write and backup controls.  \n\n---\n\n## ✨ Features\n\n- **Class-oriented design** — core database logic is in the `shadeDB` class.  \n- **Persistent workflow** — one live server handles all operations.  \n- **Background persistence** — in-memory with disk persistence.  \n- **Portable** — runs on Linux, macOS, Windows, Android (via Termux).  \n- **Multipurpose CLI** — simple commands: `init`, `start`, `use`, `pull`, `get`, `update`, `remove`, `ls`, `stop`.  \n- **Config-aware** — automatically tracks the “current” DB in `~/.shadeDB/config.scdb`.  \n\n---\n\n## 🔧 Installation\n\n```bash\npip install shadeDB\n```\n\nAfter install, the `shadeDB` command is available globally. A shorter keyword for shadeDB  - **scdb**\n\n---\n\n## ⚡ Quickstart (CLI)\n\n### 1. Initialize a database  \nCreates `./mydb.scdb`, starts the server, and sets it as default:  \n```bash\nshadeDB init ./mydb.scdb backup\n```\n⚠️ Only provide the \"backup\" argument if you intend for the server to register newer backups as you make new changes. \n---\n### 2. Start database server\nThis is necessary, as the cli wrapper only communicates with the database server to retrieve,update,remove and store data.\n```bash\nshadeDB start\n```\n---\n\n### 3. Insert data  \n```bash\nshadeDB update alice.age 17 \u0026\u0026 scdb update alice.gender female\n```\n---\n\n### 4. Fetch data  \n```bash\nshadeDB get alice\n# {\"nickname\": \"Shade\", \"status\": \"active\"}\n```\n---\n\n### 5. Nested access  \n```bash\nshadeDB pull alice.nickname\n# \"Shade\"\n```\n\n---\nMaking single value updates, it is compulsory to surround with double quotes.\n### 6. Update  \n```bash\nshadeDB update alice \"my name is alice\"\n```\n\n---\n\n### 7. Remove  \n```bash\nshadeDB remove alice \n# deletes {\"nickname\":\"shade\",\"status\":\"active\"}\n```\n### 8. Remove nested \n```bash\nshadeDB remove alice.nickname\n# deletes {\"nickname\":\"shade\"} \n````\n---\n\n### 9. Check for the current database\n```bash\nshadeDB ls\n# ./mysql.scsb\n```\n\n---\n\n### 10. Switch database\n```bash\nshadeDB use ./backup.scdb backup\n# Only provide the backup argument, if it need arises.\n```\n\n---\n\n### 11. Stop server  \n```bash\nshadeDB stop\n```\n\n---\n\n## 📚 Python API  \n\nshadeDB can also be embedded directly into Python apps using the `shadeDB` class.  \n\n### 🔧 Initialize  \n```python\nfrom shadeDB.core import shadeDB\n\ndb = shadeDB(\n    file=\"./data.scdb\",\n    write=True,\n    id=True,\n    backup=False,\n    silent=False\n)\n```\n\n**Parameters**  \n- `file (str)` → Path to `.scdb` file  \n- `write (bool)` → Persist changes to disk (default: `True`)  \n- `id (bool)` → Assign unique ID per entry (default: `True`)  \n- `backup (bool)` → Keep backup copy (default: `False`) \n- `silent (bool) ` →  Whether to display a welcome message via cli on the disk's first initialisation\n---\n\n### 🛠️ Key Methods  \n\n```python\ndb.update((\"alice\", {\"nickname\": \"Shade\", \"status\": \"active\"}))   # Insert/update\ndb.get(\"alice\", multiple=True/False)      # Fetch record\ndb.get(\"alice.nickname\")  # Fetch nested value\ndb.get_context(\"alice\")   # Get full dict\ndb.get_by_id(1) # Fetch by ID\ndb.get_id(\"alice\",multiple=True/False) # Get ID of key\ndb.items()                # List all entries\ndb.import_dict({...},overwrite=True/False)     # Import dictionary, can also overwrite existing records\ndb.export_dict()          # Export to dictionary\ndb.remove(\"alice\")        # Delete entry\ndb.clear()                # Clear all\ndb.status()               # DB status\ndb.__performance__()      # Performance stats\n```\n\n---\n\n## ⚡ Example Workflow  \n\n```python\nfrom shadeDB.core import shadeDB\n\ndb = shadeDB(\"./appdata.scdb\", write=True)\n\n# Insert\ndb.update((\"alice\", {\"nickname\": \"Shade\", \"status\": \"active\"}))\n\n# Nested access\nprint(db.get(\"alice.nickname\"))   # Shade\n\n# Full context\nprint(db.get_context(\"alice\"))    # {'nickname': 'Shade', 'status': 'active'}\n\n# Export\nprint(db.export_dict())\n```\n\n---\n\n## 📑 Command \u0026 Method Reference  \n\n| Command / Method         | Description |\n|---------------------------|-------------|\n| `init \u003cfile\u003e  \u003cbackup\u003e` | Initialize DB + server |\n| `use \u003cfile\u003e \u003cbackup\u003e`             | Switch database |\n| `pull \u003ckey\u003e.\u003cvalue\u003e`      | Fetch nested record |\n| `get \u003ckey\u003e`  \u003cmultiple\u003e          | Fetch data  |\n| `update \u003ckey\u003e.\u003cvalue\u003e`   | Update existing record |\n| `remove \u003ckey\u003e`           | Delete entry ( Supports dot notation)|\n| `ls`                     | Current database |\n| `stop`                   | Stop server |\n| `update(item)`           | Insert/update via Python |\n| `get(key,multiple=True/False)`               | Fetch record |\n| `get_context(key)`       | Full dictionary view |\n| `get_by_id(id)`          | Fetch by unique ID |\n| `get_id(key,multiple=True/False)`            | Return ID of key |\n| `items()`                | List all entries |\n| `import_dict(dict,overwrite=True/False)`      | Import bulk dict |\n| `export_dict()`          | Export full dict |\n| `remove(key)`            | Delete by key/ID |\n| `clear()`                | Wipe database |\n| `status()`               | DB status info |\n| `__performance__()`      | Compile time \u0026 stats |\n\n\n\n### 🔮 Few hints on what's to come in future updates\n- **Remote mode** → optional TCP listener so shadeDB can be queried from another device (like Redis-lite networking).\n- **Replication/Sync** → lightweight push/pull sync between devices.\n- **Faster query returns** → implement a new algorithm to speed up query processing.\n- **Custom encryption algorithm** → device based encryption algorithm.\n- **Plugin system** → user-defined operations via Python modules.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharkerbyte%2Fshadedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharkerbyte%2Fshadedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharkerbyte%2Fshadedb/lists"}