# HVPDB

A controlled, encrypted database for automated systems.

HVPDB (High Velocity Python Database) is an embedded, local-first document store for Python.

It is built for durable state in automation systems.

### Key traits

* **Embedded**. Runs in your Python process. No separate server required.
* **Document store**. JSON-like documents live in named groups.
* **Durable**. Writes go to an encrypted WAL. `commit()` checkpoints atomically.
* **Transactional**. Use `begin()` for atomic commit or rollback.
* **Concurrent (by design)**. Single writer, many readers. Multi-process safety via locks.
* **Encrypted at rest**. DB + WAL use AES-256-GCM (AEAD).
* **Flexible deployment**. Single-file `.hvp` or directory-backed `.hvdb`.
* **Multiple interfaces**. Python API, CLI, and optional HTTP server.

{% hint style="info" %}
HVPDB is RAM-backed. Plan memory for the full dataset.
{% endhint %}

### Install

```bash
pip install hvpdb
```

Optional extras:

```bash
pip install "hvpdb[passkey]"   # FIDO2 / Passkey auth support
pip install "hvpdb[server]"    # FastAPI HTTP server
pip install "hvpdb[full]"      # All extras
```

Need the full install matrix? See [Installation](https://8w6s.gitbook.io/hvpdb/getting-started/installation).

### Quick example (Python)

```python
from hvpdb import HVPDB

db = HVPDB("my_database.hvp", password="secure-password")

users = db.group("users")
users.insert({"name": "Alice", "role": "admin"})

for user in users.find({"role": "admin"}):
    print(user)

db.commit()
db.close()
```

<a href="https://github.com/8w6s/hvpdb" class="button primary" data-icon="github">GitHub repository</a>

### Start here

* [Quickstart](https://8w6s.gitbook.io/hvpdb/getting-started/quickstart)
* [Installation](https://8w6s.gitbook.io/hvpdb/getting-started/installation)
* [Core concepts](https://8w6s.gitbook.io/hvpdb/concepts/core-concepts)
* [Python API](https://8w6s.gitbook.io/hvpdb/reference/python-api)
* [CLI](https://8w6s.gitbook.io/hvpdb/reference/cli)

### Deep dives

* [Architecture & data flow](https://8w6s.gitbook.io/hvpdb/concepts/architecture-and-data-flow)
* [On-disk format (.hvp / .hvdb)](https://8w6s.gitbook.io/hvpdb/concepts/on-disk-format-.hvp-.hvdb)
* [Cluster mode](https://8w6s.gitbook.io/hvpdb/concepts/cluster-mode)
* [Write-ahead log (WAL)](https://8w6s.gitbook.io/hvpdb/concepts/write-ahead-log-wal)
* [Transactions](https://8w6s.gitbook.io/hvpdb/concepts/transactions)
* [Indexing & query execution](https://8w6s.gitbook.io/hvpdb/concepts/indexing-and-query-execution)
* [Concurrency, locks, and consistency](https://8w6s.gitbook.io/hvpdb/concepts/concurrency-locks-and-consistency)
* [Deep dive spec (internal)](https://8w6s.gitbook.io/hvpdb/reference/deep-dive-spec-internal)

### Security

* [Security model](https://8w6s.gitbook.io/hvpdb/security/security-model)
* [Cryptography & key derivation](https://8w6s.gitbook.io/hvpdb/security/cryptography-and-key-derivation)

### Operations

* [Diagnostics](https://8w6s.gitbook.io/hvpdb/operations/diagnostics)
* [Maintenance](https://8w6s.gitbook.io/hvpdb/operations/maintenance)
* [Backup & recovery](https://8w6s.gitbook.io/hvpdb/operations/backup-and-recovery)
* [Performance & limits](https://8w6s.gitbook.io/hvpdb/operations/performance-and-limits)
* [Troubleshooting](https://8w6s.gitbook.io/hvpdb/operations/troubleshooting)

### Reference add-ons

* [Connection URI](https://8w6s.gitbook.io/hvpdb/reference/connection-uri)