beaver-db 2.4.0

beaver is a simple, local, and embedded database designed to manage complex, modern data types without requiring a database server, built on top of SQLite.

Design Philosophy

beaver is built with a minimalistic philosophy for small, local use cases where a full-blown database server would be overkill.

• Minimal Dependencies: The core library has minimal dependencies (numpy, pydantic, rich, typer). Advanced features (like the REST server) are optional extras.
• Safe Concurrency: Thread-safe and multi-process-safe by default, with robust inter-process locking.
• Local-First: A single, portable SQLite file is the default.
• Fast & Performant: Zero network latency for local operations and an optional, in-memory read cache.
• Standard SQLite: The database file is 100% compatible with any standard SQLite tool, ensuring data portability.
• Pythonic API: Designed to feel like a natural extension of your code, using standard Python data structures and Pydantic models.

Installation

Install the core library:

pip install beaver-db

Note: beaver-db 2.0 is currently in release-candidate cycle. The CLI (beaver command), REST API server (beaver serve), BeaverClient remote, and the published Docker image are all landing in 2.0 final (target: June 2026). Today the library is consumed as a Python API only. Track progress at vault/Atlas/Architecture/2026-05-15-beaver-v2-release-plan.md in the workspace, or watch the 2.0 issues on GitHub.

Quickstart

Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.

from beaver import BeaverDB, Document

# 1. Initialize the database
db = BeaverDB("data.db")

# 2. Use a namespaced dictionary for app configuration
config = db.dict("app_config")
config["theme"] = "dark"
print(f"Theme set to: {config['theme']}")

# 3. Use a persistent list to manage a task queue
tasks = db.list("daily_tasks")
tasks.push("Write the project report")
tasks.push("Deploy the new feature")
print(f"First task is: {tasks[0]}")

# 4. Use a document collection for storage + full-text search
articles = db.docs("articles")
doc = Document(
    id="sqlite-001",
    body="SQLite is a powerful embedded database ideal for local apps.",
)
articles.index(document=doc)

# Perform a full-text search
results = articles.search("database")
top = results[0]
print(f"FTS Result: '{top.document.body}' (score={top.score:.2f})")

db.close()

Features

• Key-Value Dictionaries: A Pythonic, dictionary-like interface for storing any JSON-serializable object or Pydantic model within separate namespaces. Includes TTL support for caching.
• Blob Storage: A dictionary-like interface for storing binary data (e.g., images, PDFs) with associated JSON metadata.
• Persistent Lists: A full-featured, persistent Python list supporting push, pop, prepend, deque, slicing, and in-place updates.
• Persistent Priority Queue: A high-performance, persistent priority queue perfect for task orchestration across multiple processes.
• Probabilistic Sketches: Track cardinality and membership for millions of items in constant space using HyperLogLog and Bloom Filters.
• Document Collections: Store rich documents combining a vector embedding and Pydantic-based metadata.
• Vector Search: Fast, multi-process-safe linear vector search using an in-memory numpy-based index.
• Full-Text & Fuzzy Search: Automatically index and search through document metadata using SQLite's FTS5 engine, with optional fuzzy search for typo-tolerant matching.
• Knowledge Graph: Create directed, labeled relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
• Pub/Sub System: A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture.
• Time-Indexed Logs: A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view.
• Event-Driven Callbacks: Listen for database changes in real-time. Subscribe to events on specific managers to trigger workflows or update UIs.
• Inter-Process Locking: Robust, deadlock-proof locks. Use db.lock('task_name') to coordinate arbitrary scripts, or with db.list('my_list') as l: to perform atomic, multi-step operations.
• Pydantic Support: Optionally associate pydantic.BaseModels with any data structure for automatic, recursive data validation and (de)serialization.
• Data Export: Dump most data structures to a portable JSON file with a single .dump() command. (Full backup/restore symmetry — .load() across all managers, plus the beaver CLI and REST server — lands in 2.0 final; tracked in issues #15, #18, #36.)

Documentation

For a complete API reference, in-depth guides, and more examples, please visit the official documentation at:

https://syalia.com/beaver

Contributing

Contributions are welcome! If you think of something that would make beaver more useful for your use case, please open an issue or submit a pull request.

License

This project is licensed under the MIT License.