binarydb

Biblioteca pequeña de base de datos key-value persistente en memoria con serialización a disco.

Estado: Proyecto en desarrollo - no terminado -. Se acepta y agradece colaboración.

Hecho por: Raúl Novo

Descripción

binarydb proporciona una implementación sencilla y fiable de un almacén clave-valor en memoria con persistencia mediante serialización (pickle). Está pensada para conjuntos de datos pequeños a medianos donde la simplicidad y la embebibilidad importan más que la máxima velocidad.

Características principales:

• Almacenamiento en memoria con guardado atómico a disco.
• API simple: set, get, delete, update, commit, load.
• Soporte básico de transacciones (begin/rollback/end).

Archivos y módulos

• binarydb/__init__.py — inicialización del paquete.
• binarydb/database.py — implementación principal de la clase Database y la lógica de persistencia. Ver archivo
• binarydb/errors.py — excepciones personalizadas usadas por la librería. Ver archivo
• binarydb/cache.py — (pendiente / utilidad relacionada con caché).
• binarydb/index.py — (pendiente / estructuras de índice).
• binarydb/lock.py — (pendiente / gestión de bloqueo para concurrencia).
• binarydb/transaction.py — (pendiente / helpers de transacción).
• binarydb/utils.py — (pendiente / funciones auxiliares).
• binarydb/wal.py — (pendiente / write-ahead log).

Nota: Algunos módulos están vacíos o en desarrollo; la descripción refleja el estado actual del código.

Ejemplo de uso

from binarydb.database import Database

db = Database("./datos/mydb")
db.load()  # cargar si existe
db.set("usuario:1", {"nombre": "Ana", "edad": 30})
print(db.get("usuario:1"))
db.commit()
db.close()

Contribuciones

Este proyecto no está terminado. Si quieres contribuir, abre issues o pull requests. Agradezco cualquier aportación: correcciones, tests, funciones faltantes (índices, WAL, locking, ...), o mejoras de documentación.

Licencia

Este proyecto está licenciado bajo la GNU General Public License v3 (GPL-3.0).

Resumen breve: puedes usar, modificar y redistribuir este código libremente; sin embargo, si redistribuyes el código o versiones modificadas, debes hacerlo bajo la misma licencia (GPL v3) y conservar el crédito al autor original (Raúl Novo). Para el texto completo de la licencia, consulta: Licencia GNU GPL v3.

API (resumen)

Clase principal: Database (implementada en binarydb/database.py).

• Database(path: str | Path) — constructor; la ruta recibida se guarda con sufijo .pkl.
• load() — carga la base de datos desde disco (si existe).
• commit() — persiste los datos en disco usando reemplazo atómico.
• set(key: str, value: Any) — insertar o sobrescribir una clave.
• get(key: str, default: Any = None) -> Any — recuperar valor.
• delete(key: str) — eliminar clave si existe.
• update(key: str, changes: dict[str, Any]) — actualizar campos de un registro tipo dict.
• exists(key: str) -> bool — comprobar existencia.
• all() -> dict[str, Any] — copia superficial de todos los registros.
• begin() — iniciar una transacción (snapshot en memoria).
• rollback() — restaurar el snapshot y deshacer cambios de la transacción activa.
• end() — finalizar transacción y hacer commit.
• close() — guarda cambios pendientes (si los hay) y marca la base de datos como cerrada.

Estado actual de los módulos

• binarydb/database.py: implementado (clase Database). Ver archivo
• binarydb/errors.py: implementado (excepciones). Ver archivo
• binarydb/cache.py: contiene definiciones mínimas; revisar su propósito y completar la funcionalidad. Ver archivo
• binarydb/index.py: vacío / pendiente
• binarydb/lock.py: vacío / pendiente
• binarydb/transaction.py: vacío / pendiente (aunque Database implementa control básico de transacciones en memoria)
• binarydb/utils.py: vacío / pendiente
• binarydb/wal.py: vacío / pendiente