rochedb 0.1.3

Pure Python TCP driver for RocheDB

RocheDB Python Driver

Pure Python TCP driver for RocheDB.

This driver talks to roched over RocheDB's high-level wire protocol. It does not reimplement RocheDB's ring-key, period, head-angle, or placement rules. Applications pass a human-readable ring name, and RocheDB returns a typed ID.

Status

• package: PyPI rochedb v0.1.3
• current mode: native TCP wire driver
• Python: 3.10+
• runtime dependencies: none
• RocheDB core: running roched node or cluster

Implemented:

• persistent TCP connections
• wire_version / health
• put / put_codec / put_json / put_nif / put_bif
• get / get_encoded / get_text / get_json
• query / query_encoded / query_text / query_json
• codec metadata negotiation with CODECMETA ON
• batch_get
• typed RocheId
• one reconnect retry
• context manager support

Planned:

• authentication / secret-key handshake support
• retrieve / atlas wire APIs once the public wire contract is finalized for drivers
• ring-read filters/projection once the public wire contract is finalized for drivers
• connection pooling

Install

Install the published package from PyPI:

python3 -m pip install rochedb

For local driver development, install from a checkout:

python3 -m pip install -e .

Build roched from the RocheDB core repository:

git clone https://github.com/puffball1567/rochedb.git
cd rochedb
nimble install -y
nim c -d:release --nimcache:/tmp/nimcache_roched -o:src/roched src/roched.nim

Example

from rochedb import RocheClient

with RocheClient.connect("127.0.0.1:17301") as db:
    doc_id = db.put_json(
        "docs/japan/support",
        {"title": "Tokyo support note", "country": "JP"},
        vector=[1.0, 0.0],
    )

    print(db.get_json(doc_id))
    print(db.get_encoded(doc_id).codec)
    print(db.query_json(doc_id, "{ title }"))

Test

From this driver repository, point ROCHEDB_CORE_DIR at a RocheDB checkout:

ROCHEDB_CORE_DIR=/path/to/rochedb python3 -m unittest discover -s tests

The test starts a two-node local roched cluster and verifies put/get/query, JSON helpers, codec metadata, BIF opaque payloads, wire_version, and batch_get.

Why A Native Wire Driver?

The Python driver is intended for API services, scripts, experiments, and AI/RAG validation where a running RocheDB server or cluster is the natural boundary. It keeps Python out of RocheDB's placement internals and uses the same ring-oriented API that other external drivers should use.