Adapters Module (hierachain/adapters/*)

1. Overview

The adapters module provides the persistence layer for HieraChain. The core system defines common interfaces for database operations, allowing operators to select or switch database backends without changing business logic or consensus code.

Main roles

• Standardizes database read and write operations for chains, blocks, events, proofs, and entity state.
• Supports multiple environments, from local development (SQLite, in-memory) to production clusters (PostgreSQL, Redis).
• Enforces data isolation and input sanitization across database engines.

2. Available database adapters

All storage adapters reside in hierachain/adapters/database/.

2.1 SQLite Database Adapter (sqlite_adapter.py)

The default adapter for development, testing, and single-node setups.

• Technology: SQLite3 via sqlite3 and hierachain/adapters/database/base/sql_base.py.
• Schema: Initialized through sqlite_schema.py, creating tables for chains, blocks, events, proofs, and chain_state.
• Strengths: Zero external service dependencies, ACID guarantees, single-file backups.
• Indexes: Built on entity_id, event_type, block_number, and timestamp.

2.2 PostgreSQL Database Adapter (postgres_adapter.py)

The relational database adapter for multi-node and enterprise deployments.

• Technology: PostgreSQL with connection pooling.
• Schema: Initialized through postgres_schema.py using identical schema semantics to SQLite.
• Strengths: High concurrent write capacity, connection pooling, enterprise backup tooling.
• Query features: Partition-aware queries and index scans for high-volume audit logs.

2.3 Redis Database Adapter (redis_adapter.py)

An in-memory adapter designed for high-throughput reads and real-time entity state lookups.

• Technology: Redis via redis-py.
• Data structures: Hashes for block headers and event payloads, sorted sets for chronological event ordering and block index ranges, and sets for unique chain identifiers.
• Strengths: Low-latency point lookups and fast entity tracing.
• Persistence: Dependent on Redis RDB snapshots and AOF configuration.

3. Adapter comparison

4. Configuration and usage

Configuration via settings

Set the storage backend using environment variables:

# Available backends: sqlite, postgres, redis, memory
export HRC_STORAGE_BACKEND=sqlite
export DATABASE_URL="sqlite:///data/ledger.db"

# Or for PostgreSQL
# export HRC_STORAGE_BACKEND=postgres
# export DATABASE_URL="postgresql://user:pass@localhost:5432/hierachain"

Usage in code

Using SQLite

from hierachain.adapters.database.sqlite_adapter import SQLiteAdapter

adapter = SQLiteAdapter("data/ledger.db")
stats = adapter.get_chain_statistics("supply_chain_ledger")
print(f"Total blocks: {stats['total_blocks']}")

Using PostgreSQL

from hierachain.adapters.database.postgres_adapter import PostgreSQLAdapter

adapter = PostgreSQLAdapter(connection_string="postgresql://user:pass@localhost:5432/hierachain")
stats = adapter.get_chain_statistics("supply_chain_ledger")
print(f"Total blocks: {stats['total_blocks']}")

Using Redis

from hierachain.adapters.database.redis_adapter import RedisAdapter

adapter = RedisAdapter(host="localhost", port=6379, db=0)
stats = adapter.get_chain_statistics("supply_chain_ledger")
print(f"Total blocks: {stats['total_blocks']}")

5. Security and validation

Path traversal protection

Adapters validating file paths or chain names enforce strict pattern matching:

• Names allow alphanumeric characters, underscores _, and hyphens -.
• Path traversal sequences (.., /, \) are rejected before executing filesystem or query commands.

Secure logging

Adapters log queries and connection events through SecureLogger, redacting database credentials, auth tokens, and sensitive business details.

6. Maintenance and retention

• Data cleanup: Relational adapters support purging historical event logs beyond retention thresholds set by HRC_SQL_RETENTION_DAYS.
• Logging and journals: Persistent binary journals and forensic error records use hierachain/core/parquet_log.py and hierachain/error_mitigation/journal.py, keeping chain persistence decoupled from diagnostic logging.

Related

• Storage Module
• Configuration Reference
• Security Overview