Part of the EmbeddedOS ecosystem.
eDB is a unified multi-model database that combines SQL, Document/NoSQL, and Key-Value storage in a single embedded engine. It includes a Python backend (FastAPI + SQLite), a React/TypeScript frontend with SQL editor and AI-powered query assistance, and a standalone browser version.
| Feature | Description |
|---|---|
| 🗃️ Multi-Model Storage | SQL tables, JSON documents, and key-value pairs — all in one database |
| 🔐 JWT Authentication | Access and refresh tokens with configurable expiration |
| 👥 RBAC | Admin, read_write, read_only roles with granular permissions |
| 🔒 AES-256 Encryption | Field-level encryption at rest using AES-256-GCM |
| 📋 Audit Logging | Tamper-resistant logs with hash chain verification |
| 🤖 eBot AI | Natural language → SQL/NoSQL translation |
| 🌐 REST API | Full CRUD via FastAPI with auto-generated OpenAPI docs |
| 🛡️ Input Sanitization | SQL injection, NoSQL injection, and prompt injection detection |
| ⚡ Zero Dependencies | Core engine runs on SQLite — no external database needed |
| 📦 Embeddable | Use as a Python library or standalone server |
| 🖥️ React Frontend | Table management, inline editing, SQL query editor, eBot sidebar |
| 🌐 Browser Standalone | Self-contained single-file HTML version with localStorage persistence |
git clone https://github.com/embeddedos-org/eDB.git
cd eDB
pip install -e ".[dev]"
# Initialize database
edb init
# Create admin user (interactive password prompt)
edb admin create --username admin
# Start the server
edb serve --port 8000
# API docs at http://localhost:8000/docsnpm install
npm run devThe React UI runs at http://localhost:5178.
Open browser/edb.html directly in any browser for a zero-install experience with localStorage persistence.
from edb.core.database import Database
from edb.core.models import ColumnDefinition, ColumnType, TableSchema
db = Database("my_app.db")
# SQL
schema = TableSchema(name="users", columns=[
ColumnDefinition(name="id", col_type=ColumnType.INTEGER, primary_key=True),
ColumnDefinition(name="name", col_type=ColumnType.TEXT),
])
db.sql.create_table(schema)
db.sql.insert("users", {"id": 1, "name": "Alice"})
# Documents
db.docs.insert("logs", {"event": "login", "user": "Alice"})
# Key-Value
db.kv.set("session:abc", {"user_id": 1}, ttl=3600)edb shell
# edb> SELECT * FROM users
# edb> .tables
# edb> .collectionseDB/
├── src/
│ ├── edb/ # Python backend
│ │ ├── api/ # FastAPI routes and dependencies
│ │ ├── auth/ # JWT, users, RBAC
│ │ ├── ebot/ # AI/NLP query interface
│ │ ├── query/ # Query parser and planner
│ │ ├── security/ # Encryption, audit, input validation
│ │ ├── config.py # Pydantic Settings configuration
│ │ └── cli.py # CLI entry point
│ ├── App.tsx # React main component
│ ├── main.tsx # React entry point
│ ├── styles.css # Full application styles
│ ├── components/ # React UI components
│ │ ├── TopBar.tsx # App header with controls
│ │ ├── TableList.tsx # Sidebar table navigator
│ │ ├── TableView.tsx # Data grid with inline editing
│ │ ├── QueryEditor.tsx # SQL query editor panel
│ │ ├── EBotSidebar.tsx # AI assistant sidebar
│ │ └── StatusBar.tsx # Bottom status bar
│ └── hooks/ # React hooks
│ ├── useDatabase.ts # In-memory database with CRUD
│ └── useEBot.ts # eBot AI integration
├── browser/
│ └── edb.html # Standalone browser version
├── tests/ # Python tests
├── docs/ # Documentation
├── examples/ # Runnable examples
├── package.json # Node.js project manifest
├── pyproject.toml # Python project metadata
├── vite.config.ts # Vite configuration
└── tsconfig.json # TypeScript configuration
Configure via environment variables (prefix EDB_) or .env file:
EDB_DB_PATH=my_data.db
EDB_API_HOST=0.0.0.0
EDB_API_PORT=8000
EDB_JWT_SECRET=your-strong-secret-here
EDB_ENCRYPTION_KEY=your-encryption-key
EDB_CORS_ORIGINS=http://localhost:3000,https://yourdomain.com| Variable | Description |
|---|---|
EDB_JWT_SECRET |
Required. Secret key for JWT signing. If not set, a random key is generated per session (tokens won't persist across restarts). |
EDB_ENCRYPTION_KEY |
Required. Key for AES-256-GCM encryption at rest. If not set, a random key is generated (encrypted data won't be recoverable after restart). |
EDB_CORS_ORIGINS |
Comma-separated allowed origins. Defaults to http://localhost:3000. |
Admin users are not auto-created. Use the CLI to create one:
edb admin create --username admin
# You'll be prompted for a password interactively.
# Password must be 12+ chars with uppercase, lowercase, digit, and special char.- Always set
EDB_JWT_SECRETandEDB_ENCRYPTION_KEYin production - Use strong, unique values (e.g.,
openssl rand -base64 48) - Never commit
.envfiles to version control - Restrict CORS origins to your actual frontend domains
- Review audit logs regularly via
/admin/auditendpoint
See SECURITY.md for vulnerability reporting.
pip install -e ".[dev]"
pytest
ruff check src/ tests/
ruff format src/ tests/| Command | Description |
|---|---|
npm run dev |
Start development server (port 5178) |
npm run build |
Type-check and build for production |
npm run preview |
Preview production build |
- Core multi-model engine (SQL, Document, KV)
- Query DSL with parser and planner
- JWT authentication and RBAC
- AES-256 encryption at rest
- Tamper-resistant audit logging
- REST API (FastAPI)
- eBot rule-based NL queries
- CLI (serve, init, shell)
- React frontend with SQL editor
- Browser standalone version
- CI/CD pipeline
- LLM-powered eBot (OpenAI/local models)
- Graph data model (Neo4j-style)
- Multi-node clustering (eDBE)
- GraphQL and gRPC interfaces
- File/blob storage with indexing
- Predictive analytics integration
See CONTRIBUTING.md for guidelines.
master is the line of development; every PR lands here. release is a
rolling pointer to the latest released vX.Y.Z tag, updated automatically
by .github/workflows/sync-release-branch.yml.
Tags are immutable.
See embeddedos-org/.github/STANDARDS.md for the org-wide tag scheme, release model, and the compliance frameworks every product targets.
MIT License. See LICENSE for details.
Part of the EmbeddedOS Organization.