dhara

dhara

dhara is a modern continuation of Durus, a persistent object system for applications written in the Python programming language. It could be called a noSQL database. However, it does provide "ACID" properties (Atomicity, Consistency, Isolation, Durability).

The implementation of dhara is not multi-threaded but does provide concurrency via a client/server model. It is optimized for read heavy work loads and aggressively caches persistent objects in memory. For many applications, this design enables good performance with minimal effort from application programmers.

Origin

dhara was originally written by the MEMS Exchange software development team at the Corporation for National Research Initiatives (CNRI). dhara was designed to be the storage component for the Python-powered web sites operated by the MEMS Exchange. See doc/README_CNRI.txt for more details.

Overview

dhara offers an easy way to use and maintain a consistent collection of object instances used by one or more processes. Access and change of a persistent instances is managed through a cached Connection instance which includes commit() and abort() methods so that changes are transactional.

CLI Commands

Dhara provides a unified CLI with three command groups:

MCP Server Commands (for AI/Agent Workflows)

dhara mcp start              # Start MCP server
dhara mcp stop               # Stop MCP server
dhara mcp status             # Check server status
dhara mcp health             # Health check

Database Commands (Dhara Storage Operations)

dhara db start               # Start Dhara storage server
dhara db client              # Connect to server (interactive)
dhara db pack                # Reclaim storage space

Common options for database commands:

• --file PATH or -f PATH - Database file path
• --host HOST or -h HOST - Server host (default: 127.0.0.1)
• --port PORT or -p PORT - Server port (default: 2972)
• --readonly - Open in read-only mode

Dhara-Specific Commands

dhara adapters               # List registered adapters
dhara storage                # Display storage information
dhara admin                  # Launch admin shell (IPython)

Validation

The preferred local validation path is crackerjack:

python -m crackerjack qa-health
python -m crackerjack run-tests

Use direct pytest commands when you need to isolate a single file or debug a specific failure.

Configuration Surfaces

Dhara currently exposes two configuration layers:

• dhara.core.config.DharaSettings is the canonical runtime settings model for the CLI and MCP server
• dhara.config remains available for lightweight dataclass helpers and compatibility with older code

For service startup, operator configuration, and environment-variable overrides, use DharaSettings.

Deprecation Policy

Dhara is in an active compatibility-reduction window.

• Deprecated compatibility imports remain available in 0.8.x
• They are planned for stronger enforcement in 0.9.x
• Convenience compatibility shims are candidates for removal in 1.0.0

The current policy and migration targets are documented in docs/LEGACY_COMPATIBILITY_AND_REMOVAL_PLAN.md.

Quick Demo

Start a Dhara server:

dhara db start

This starts a Dhara storage server using a temporary file and listening for clients on localhost port 2972.

Connect as a client:

dhara db client

This opens an interactive IPython shell connected to the storage server. You have access to a dictionary-like persistent object, root. If you make changes to items of root and run connection.commit(), the changes are written to the file. If you make changes and then run connection.abort(), the attributes revert back to the values they had at the last commit.

Multiple clients: Run dhara db client in another terminal to see how committed changes to root in one client are available in other clients when they synchronize via connection.abort() or connection.commit().

Stop the server: Press Control-C in the server terminal.

Persistence example:

# Start server with a persistent file
dhara db start --file test.dhara

# Connect, make changes, commit
dhara db client --file test.dhara
# In the shell:
# >>> root["hello"] = "world"
# >>> connection.commit()