Metadata-Version: 2.4
Name: dnhydb
Version: 0.2.0
Classifier: Development Status :: 3 - Alpha
Classifier: License :: Other/Proprietary License
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Dist: tomli>=1.1 ; python_full_version < '3.11'
Requires-Dist: numpy>=1.22 ; extra == 'numpy'
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: numpy>=1.22 ; extra == 'test'
Provides-Extra: numpy
Provides-Extra: test
License-File: LICENSE.md
License-File: THIRD-PARTY-LICENSES.txt
Summary: dNHyDB (directNHyDB) – general-purpose database with direct addressing (u, v, side); native Rust engine with Python bindings
Keywords: database,storage-engine,rust,numpy,append-only
Author-email: Achim Meissner <achim.meissner@nhydb.de>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# dNHyDB (directNHyDB)

**dNHyDB** is a general-purpose database with **direct structural
addressing** `(R1, u, v, s)`: `u` is the record, `v` the field or position
(both `u64`, 1 … 2^64−1), `s` the side (NL/NR). Ordinary records and fields
work without tables or a primary index – the address space itself provides
order. The NHyDB number `N = G² − u` (NL) or `G² + v` (NR) with `G = u + v` is
computed arithmetically when needed and is never a storage key.

The storage engine is written in native Rust; the Python package `dnhydb`
binds it via PyO3 and offers single operations, NumPy batches and iterators.

Version: **0.2.0** · Platforms: Linux, macOS, Windows · License: see
[`LICENSE.md`](LICENSE.md)

## Features

* Native Rust core (`crates/dnhydb-core`) without Python dependency;
  dependencies only `crc32fast`, `miniz_oxide`, `libc`.
* Python package `dnhydb` (PyO3) with single-value API, NumPy batches and
  iterators.
* One writer (exclusive lock), any number of readers with snapshot isolation
  at the commit boundary and `refresh()`.
* Append-only container with two CRC-protected superblocks: after a crash the
  last commit is valid, never half a batch.
* Write buffer, commit policy (manual or thresholds, no background thread),
  transactions with rollback, durability `fsync` / `full` / `none`.
* Catalog side file for fast opening, iterators that skip gaps, configurable
  caches, VALUE secondary index, compaction, repair, verify/health.

## Installation

From PyPI (prebuilt wheels for CPython 3.9–3.14 on Linux x86_64/aarch64,
macOS x86_64/arm64 and Windows x64):

```bash
pip install dnhydb
pip install numpy          # optional, for the NumPy batch API
```

The same files are attached to each release on the *Releases* page of the
repository.

From source (requires a Rust toolchain, see [`BUILDING.md`](BUILDING.md)):

```bash
pip install .
```

## Quick start (Python)

```python
import dnhydb

with dnhydb.create("data.dnhydb") as db:
    db.define_base([("date", "u64"), ("text", "utf8")])
    with db.transaction():
        db.put_record(1, [20261015, "Hello"])
        db.put_cell(1, 1_000_001, "A poem …")

reader = dnhydb.open_reader("data.dnhydb")
print(reader.get_cell(1, 1_000_001))
for v, value in reader.cells(1):
    print(v, value)
print(dnhydb.n_of(1, 1_000_001), dnhydb.address_of(dnhydb.n_of(1, 1_000_001)))
```

## Quick start (Rust)

```rust
use dnhydb_core::{Db, Options, Lane, TypeCode, Val, FieldSpec};

let mut db = Db::create("data.dnhydb", Options::default())?;
db.define_base(&[FieldSpec::new("date", TypeCode::U64), FieldSpec::new("text", TypeCode::Utf8)], None)?;
db.put_record(1, &Val::List(vec![Val::from(20261015u64), Val::from("Hello")]), &[], Lane::NL)?;
db.put_cell(1, 1_000_001, Val::from("A poem"), Lane::NL)?;
db.commit()?;

let r = Db::open_reader("data.dnhydb", Options::default())?;
for c in r.cells(1, 1..=u64::MAX, Lane::NL) {
    let (v, value) = c?;
}
```

Command line: `dnhydb --help` (or `python -m dnhydb`).

## Configuration

All options are optional; see
[`config/dnhydb_config.example.toml`](config/dnhydb_config.example.toml).

## Known limitations

* **Scope:** one realm (R1) and the CLASSIC layout only; `u` and `v` are
  `u64`; integer values up to `i128`.
* **One writer at a time** (exclusive lock on `<file>.lock`: `flock` on
  Unix, `LockFileEx` on Windows); readers see the state of the last commit
  and call `refresh()` for newer commits.
* **Durability `full`:** on macOS `F_FULLFSYNC` is used; if the file system
  rejects it, dNHyDB falls back to a plain `fsync` without reporting an
  error. On Linux `full` is the same as `fsync`; on Windows both use
  `FlushFileBuffers`. Directory entries are synced on Unix only (Windows:
  NTFS journal).
* **Platforms:** Linux (x86_64, aarch64), macOS (x86_64, arm64) and Windows (x64), CPython 3.9–3.14. On Windows, replacing the
  database file while readers hold it open (compaction) uses POSIX rename
  semantics (Windows 10 or newer, NTFS).

## Documentation

* [Technical documentation (English)](docs/en/dNHyDB_Technical_Documentation.md)
* [Technische Dokumentation (Deutsch)](docs/de/dNHyDB_Technische_Dokumentation.md)
* [`BUILDING.md`](BUILDING.md) – building wheels from source
* [`RELEASING.md`](RELEASING.md) – versioning and release procedure
* [`CHANGELOG.md`](CHANGELOG.md)

## Tests and benchmarks

```bash
cargo test -p dnhydb-core --release     # Rust core
pip install ".[test]"
python -m pytest tests/python           # Python package (against the installed wheel)

cargo run --release -p dnhydb-core --example bench -- 1000000 target/bench-tmp
python benchmarks/bench_numpy.py
```

## Repository layout

```text
crates/dnhydb-core  native Rust core (format, codec, addresses, engine)
crates/dnhydb-py    PyO3 binding (the only place with Python dependencies)
python/dnhydb       Python package and CLI
tests/python        Python tests
benchmarks/         NumPy benchmark
config/             example configuration
docs/               documentation (de, en)
.github/workflows/  CI: tests and wheels
```

## Scientific Background

The mathematical foundations and database architecture are described in:

Das Dynadron als mathematisches Datenbankprinzip

https://doi.org/10.5281/zenodo.22549415

https://doi.org/10.5281/zenodo.23438748

https://doi.org/10.5281/zenodo.22694525

## License

dNHyDB is licensed under the **NHyDB / dNHyDB Experimental Software License 1.0**
([`LICENSE.md`](LICENSE.md)). The source code is available, but this is
**not an open-source license**: free use is limited to non-production
purposes (unlimited for private individuals, time-limited for teaching,
research and businesses), and **production use is not permitted** without a separate written license. Please read the
license text before using the software.

The compiled extension module contains third-party Rust components (all
under MIT/Apache-2.0-style licenses); their notices are in
[`THIRD-PARTY-LICENSES.txt`](THIRD-PARTY-LICENSES.txt), which is also shipped
inside the wheel.

## Contact

Achim Meissner – achim.meissner@nhydb.de

