Skip to main content

​
What is BinaryDB?

BinaryDB is a lightweight, embeddable key-value database that stores data in memory with persistent serialization to disk. It’s designed for small to medium datasets where simplicity, reliability, and ease of integration matter more than maximum performance.
BinaryDB is currently in active development. Some advanced features like write-ahead logging (WAL), indexing, and advanced concurrency controls are planned but not yet implemented.

​
Why BinaryDB?

BinaryDB fills the gap between simple file-based storage and full-featured database systems. It’s perfect for:
  • Embedded applications that need persistent storage without external dependencies
  • Prototyping and development where you need a simple data store quickly
  • Small to medium datasets where in-memory storage is feasible
  • Python projects that want to avoid complex database setups

​
Key Features

In-Memory Storage

All data is kept in memory for fast access, with atomic persistence to disk when you commit changes.

Simple API

Intuitive methods like set(), get(), delete(), and update() make it easy to work with your data.

Transaction Support

Basic transaction control with begin(), rollback(), and end() to safely manage changes.

Atomic Persistence

Changes are written to disk atomically using file replacement to prevent corruption.

​
Core Capabilities

​
Persistent Key-Value Storage

BinaryDB provides a dictionary-like interface where you store any Python object against a string key: 
db.set("user:1", {"name": "Ana", "age": 30})
db.set("config", {"theme": "dark", "language": "en"})
db.set("counter", 42)

​
Atomic Commits

Changes are only persisted to disk when you explicitly call commit(). This ensures data integrity: 
db.set("key", "value")
db.commit()  # Now safely stored on disk

​
Transaction Control

Wrap multiple operations in a transaction to ensure they succeed or fail together: 
db.begin()
try:
    db.set("balance", 1000)
    db.set("last_updated", "2026-03-04")
    db.end()  # Commit transaction
except Exception:
    db.rollback()  # Undo all changes

​
Architecture

BinaryDB uses Python’s pickle module for serialization and pathlib for file operations. It requires only the Python standard library—no external dependencies. 
┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
         ├── set/get/delete
         ├── commit/load
         └── begin/rollback/end
         │
┌────────▼────────┐
│  Database API   │
└────────┬────────┘
         │
    ┌────┴────┐
    │ Memory  │  (dict storage)
    └────┬────┘
         │
    ┌────▼────┐
    │  Disk   │  (pickle serialization)
    └─────────┘

​
Security Warning

Never load database files from untrusted sources.BinaryDB uses Python’s pickle module for serialization, which can execute arbitrary code during deserialization. Only load database files that you created yourself or that come from trusted sources.

​
Design Goals

BinaryDB prioritizes:
  1. Simplicity - Easy to understand, easy to integrate
  2. Reliability - Atomic operations prevent data corruption
  3. Embeddability - No external dependencies or server processes
  4. Correctness - Clear error handling and validation

​
What BinaryDB Is Not

BinaryDB is not suitable for:
  • Large datasets that don’t fit in memory
  • High-concurrency multi-process scenarios
  • Distributed systems requiring replication
  • Production systems requiring advanced query capabilities
  • Situations where you need SQL or complex queries
For these use cases, consider traditional databases like PostgreSQL, SQLite, or Redis.

​
Project Status

BinaryDB is an active development project created by Raúl Novo. The core database functionality is implemented and stable, but several advanced features are planned:
  • ✅ Core CRUD operations
  • ✅ Atomic persistence
  • ✅ Basic transactions
  • ✅ Error handling
  • 🚧 Write-ahead logging (WAL)
  • 🚧 Indexing support
  • 🚧 Advanced locking mechanisms
  • 🚧 Caching layer
Contributions are welcome! If you’d like to help improve BinaryDB, feel free to open issues or submit pull requests.

​
License

BinaryDB is licensed under the GNU General Public License v3 (GPL-3.0). You can freely use, modify, and redistribute the code, but any redistributed versions must also be under GPL v3 and credit the original author.

​
Next Steps

Installation

Learn how to get BinaryDB and add it to your project

Quick Start

Build your first BinaryDB application in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us