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.0is currently in release-candidate cycle. The CLI (beavercommand), REST API server (beaver serve),BeaverClientremote, 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 atvault/Atlas/Architecture/2026-05-15-beaver-v2-release-plan.mdin the workspace, or watch the2.0issues 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, orwith 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 thebeaverCLI and REST server — lands in2.0final; tracked in issues #15, #18, #36.)
Documentation
For a complete API reference, in-depth guides, and more examples, please visit the official documentation at:
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.
1 maintainer
Metadata
1 maintainer
Release files for beaver-db 2.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| beaver_db-2.4.1.tar.gz | 1.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| beaver_db-2.4.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / beaver_db-2.4.1.tar.gz
| Download URL | beaver_db-2.4.1.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2d659acdc3c80692f6e096fac67624e9929a0e49850cb3cdf05ce84c0e925b12
|
|
BLAKE2b-256 checksum How to use checksums |
ffd9b920b935f5fdb17510bec9ec748afccb9e27f23aaa1ee229f5d01efc6a39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / beaver_db-2.4.1-py3-none-any.whl
| Download URL | beaver_db-2.4.1-py3-none-any.whl |
|---|---|
| Size | 87.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a8752896e1e85de5bddaef13f26e861bc4828938f0c1535b423b5c49f56e78b
|
|
BLAKE2b-256 checksum How to use checksums |
ad188e30c2cbe34429c8f277a7dc3cb7f69344778ef5b9d56e8aed84fce6acba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
