diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 531e0c4e..937f82e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,16 +51,16 @@ This project adheres to a code of conduct that all contributors are expected to 1. **Build the C++ components**: ```bash # Build debug version without tests - ./build.sh + ./scripts/build.sh # Build debug version with tests - ./build.sh -t + ./scripts/build.sh -t # Build release version - ./build.sh -r + ./scripts/build.sh -r # Build release version with tests - ./build.sh -r -t + ./scripts/build.sh -r -t ``` Alternatively, you can use Meson directly: @@ -92,16 +92,16 @@ This project adheres to a code of conduct that all contributors are expected to meson test -C build # Run Python tests (excludes stress tests) - ./run_tests.sh + ./scripts/run_tests.sh # Run specific Python test - ./run_tests.sh -k=test_name + ./scripts/run_tests.sh -k=test_name # Run stress tests only (takes longer) - ./run_stress_tests.sh + ./scripts/run_stress_tests.sh # Run specific stress test - ./run_stress_tests.sh -k=test_name + ./scripts/run_stress_tests.sh -k=test_name ``` ## How to Contribute diff --git a/README.md b/README.md index a74fdd76..6374874d 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,42 @@ -# dbzero +

+ dbzero logo +

**A state management system for Python 3.x that unifies your application's business logic, data persistence, and caching into a single, efficient layer.** [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) +> "If we had infinite memory in our laptop, we'd have no need for clumsy databases. Instead, we could just use our objects whenever we liked." +> +> — Harry Percival and Bob Gregory, *Architecture Patterns with Python* + ## Overview **dbzero** lets you code as if you have infinite memory. Inspired by a thought experiment from *Architecture Patterns with Python* by Harry Percival and Bob Gregory, dbzero handles the complexities of data management in the background while you work with simple Python objects. dbzero implements the **DISTIC memory** model: - **D**urable - Data persists across application restarts -- **I**nfinite - Work with data as if memory constraints don't exist +- **I**nfinite - Work with data as if memory constraints don't exist (e.g. create lists, dicts or sets with billions of elements) - **S**hared - Multiple processes can access and share the same data -- **T**ransactions - Transaction support for data integrity -- **I**solated - Operations are isolated and thread-safe -- **C**omposable - A single process can integrate multiple memory partitions (prefixes) to suit its specific requirements +- **T**ransactional - Transaction support for data integrity +- **I**solated - Reads performed against a consistent point-in-time snapshot +- **C**omposable - Plug in multiple prefixes (memory partitions) on demand and access other apps’ data by simply attaching their prefix. -The result is a simplified application stack that eliminates the need for separate databases, ORMs and caching layers. This reduces architectural complexity and development time, while offering significant performance benefits, due to reduced serialization overhead and cache locality. +With dbzero, you don’t need separate pieces like a database, ORM, or cache layer. Your app becomes easier to build and it runs faster, because there are no roundtrips to a database, memory is used better, and you can shape your data to fit your problem. ## Key Platform Features **dbzero** provides the reliability of a traditional database system with modern capabilities and extra features on top. -- **Persistence**: Application objects (classes and common structures like `list`, `dict`, `set`, etc.) are automatically persisted to the underlying storage medium (e.g. a local file). +- **Persistence**: Application objects (classes and common structures like `list`, `dict`, `set`, etc.) are automatically persisted (e.g. to a local or network-attached file) - **Efficient caching**: Only the data actually accessed is retrieved and cached. For example, if a list has 1 million elements but only 10 are accessed, only those 10 are loaded. - **Constrained memory usage**: You can define memory limits for the process to control RAM consumption. -- **Serializable consistency**: Data changes are immediately visible to readers, maintaining a consistent view. -- **Transactions**: Make atomic changes using the `with dbzero.atomic():` context manager. +- **Serializable consistency**: Data changes can be read immediately, maintaining a consistent view. +- **Transactions**: Make atomic, exception-safe changes using the `with dbzero.atomic():` context manager. - **Snapshots & Time Travel**: Query data as it existed at a specific point in the past. This enables tracking of data changes and simplify auditing. - **Tags**: Tag objects and use tags to filter or retrieve data. -- **Indexing**: Define imperative indexes that can be dynamically created and updated. -- **Data composability**: Combine data from different apps, processes, or servers and access it through a unified interface. +- **Indexing**: Define lightweight, imperative indexes that can be dynamically created and updated. +- **Data composability**: Combine data from different apps, processes, or servers and access it through a unified interface - i.e. your application’s objects, methods and functions. - **UUID support**: All objects are automatically assigned a universally unique identifier, allowing to always reference them directly. - **Custom data models** - Unlike traditional databases, dbzero allows you to define custom data structures to match your domain's needs. @@ -187,18 +193,18 @@ with db0.snapshot(state) as snap: Organize data into independent, isolated partitions: ```python -@db0.memo(singleton=True, prefix="settings-prefix") +@db0.memo(singleton=True, prefix="/my-org/my-app/settings") class AppSettings: def __init__(self, theme: str): self.theme = theme -@db0.memo(prefix="app-data-prefix")) +@db0.memo(prefix="/my-org/my-app/data") class Note: def __init__(self, content: str): self.content = content -settings = AppSettings(theme="dark") # Data goes to "settings-prefix.db0" -note = Note("Hello dbzero!") # Data goes to "app-data-prefix.db0" +settings = AppSettings(theme="dark") # Data goes to "settings.db0" +note = Note("Hello dbzero!") # Data goes to "data.db0" ``` ### Indexes @@ -305,7 +311,8 @@ For attribution details, see [NOTICE](./NOTICE). Need help building large-scale solutions with dbzero? We offer: -- Custom UI and admin tools +- Tools for data export and manipulation +- Tools for hosting rich UI applications on top of your existing dbzero codebase - System integrations - Expert consulting and architectural reviews - Performance tuning diff --git a/assets/dbzero-brandmark.png b/assets/dbzero-brandmark.png new file mode 100755 index 00000000..0cfbbab3 Binary files /dev/null and b/assets/dbzero-brandmark.png differ diff --git a/assets/dbzero-logo.png b/assets/dbzero-logo.png new file mode 100755 index 00000000..32077e0a Binary files /dev/null and b/assets/dbzero-logo.png differ diff --git a/Dockerfile b/docker/Dockerfile similarity index 100% rename from Dockerfile rename to docker/Dockerfile diff --git a/Dockerfile-dev b/docker/Dockerfile-dev similarity index 100% rename from Dockerfile-dev rename to docker/Dockerfile-dev diff --git a/Dockerfile-package b/docker/Dockerfile-package similarity index 100% rename from Dockerfile-package rename to docker/Dockerfile-package diff --git a/Dockerfile-python-308 b/docker/Dockerfile-python-308 similarity index 100% rename from Dockerfile-python-308 rename to docker/Dockerfile-python-308 diff --git a/Dockerfile-python-309 b/docker/Dockerfile-python-309 similarity index 100% rename from Dockerfile-python-309 rename to docker/Dockerfile-python-309 diff --git a/Dockerfile-python-310 b/docker/Dockerfile-python-310 similarity index 100% rename from Dockerfile-python-310 rename to docker/Dockerfile-python-310 diff --git a/Dockerfile-python-311-debug b/docker/Dockerfile-python-311-debug similarity index 100% rename from Dockerfile-python-311-debug rename to docker/Dockerfile-python-311-debug diff --git a/Dockerfile-python-312 b/docker/Dockerfile-python-312 similarity index 100% rename from Dockerfile-python-312 rename to docker/Dockerfile-python-312 diff --git a/Dockerfile-python-313 b/docker/Dockerfile-python-313 similarity index 100% rename from Dockerfile-python-313 rename to docker/Dockerfile-python-313 diff --git a/build.sh b/scripts/build.sh similarity index 100% rename from build.sh rename to scripts/build.sh diff --git a/detect_commit.sh b/scripts/detect_commit.sh similarity index 100% rename from detect_commit.sh rename to scripts/detect_commit.sh diff --git a/run.sh b/scripts/run.sh similarity index 100% rename from run.sh rename to scripts/run.sh diff --git a/run_asan_stress_tests.sh b/scripts/run_asan_stress_tests.sh similarity index 100% rename from run_asan_stress_tests.sh rename to scripts/run_asan_stress_tests.sh diff --git a/run_asan_tests.sh b/scripts/run_asan_tests.sh similarity index 100% rename from run_asan_tests.sh rename to scripts/run_asan_tests.sh diff --git a/run_memcheck.sh b/scripts/run_memcheck.sh similarity index 100% rename from run_memcheck.sh rename to scripts/run_memcheck.sh diff --git a/run_memprof.sh b/scripts/run_memprof.sh similarity index 100% rename from run_memprof.sh rename to scripts/run_memprof.sh diff --git a/run_memtest.sh b/scripts/run_memtest.sh similarity index 100% rename from run_memtest.sh rename to scripts/run_memtest.sh diff --git a/run_prof.sh b/scripts/run_prof.sh similarity index 100% rename from run_prof.sh rename to scripts/run_prof.sh diff --git a/run_stress_tests.sh b/scripts/run_stress_tests.sh similarity index 100% rename from run_stress_tests.sh rename to scripts/run_stress_tests.sh diff --git a/run_tests.sh b/scripts/run_tests.sh similarity index 100% rename from run_tests.sh rename to scripts/run_tests.sh