Immudb — Immutable Database with Cryptographic Verification

Introduction

Immudb is an open-source immutable database by Codenotary. Every write is cryptographically hashed into a Merkle tree, making it possible to verify that no record has been altered or deleted. It targets use cases like audit trails, compliance logging, and tamper-evident record keeping.

What Immudb Does

• Stores key-value and SQL data with append-only immutability guarantees
• Generates cryptographic proofs (inclusion and consistency) for any record
• Provides a built-in SQL engine for familiar relational queries
• Tracks the full history of every key with versioned access
• Supports client-side verification so applications can independently prove data integrity

Architecture Overview

Immudb uses a custom storage engine combining a Merkle tree with an append-only commit log. Each transaction appends entries to a sequential log and updates the Merkle tree root hash. Reads verify inclusion proofs against the current root. A built-in SQL parser translates relational queries into key-value operations on the underlying store. The server exposes gRPC and HTTP APIs for client access.

Self-Hosting & Configuration

• Run via Docker or download the binary for Linux, macOS, or Windows
• Default ports: 3322 (gRPC) and 9497 (metrics/health)
• Configure data directory with --dir flag to control storage location
• Set replication with --replication-enabled for primary-replica setups
• Use environment variables IMMUDB_ADDRESS and IMMUDB_PORT for network binding

Key Features

• Cryptographic Merkle tree verification ensures tamper evidence without external tools
• Full key history with time-travel queries to retrieve any past version of a record
• Dual API supporting both key-value and SQL access patterns
• Embedded mode allows linking immudb directly into Go applications as a library
• Prometheus metrics endpoint for monitoring write throughput and verification latency

Comparison with Similar Tools

• PostgreSQL — General-purpose relational DB; lacks built-in cryptographic tamper detection
• Amazon QLDB — Managed immutable ledger; proprietary and locked to AWS
• Dolt — Git-like version control for SQL data; optimized for branching and diffing rather than cryptographic proofs
• EventStoreDB — Append-only event store; designed for event sourcing patterns rather than general immutable storage
• SQLite — Embedded single-file database; no immutability or verification features

FAQ

Q: Can I delete data from immudb? A: By design, data cannot be physically deleted. You can mark entries as logically obsolete, but the original record and its hash remain in the Merkle tree for audit purposes.

Q: Does immudb support SQL joins? A: Yes. The built-in SQL engine supports SELECT, JOIN, GROUP BY, and other standard operations. Complex analytical queries may be slower than purpose-built OLAP engines.

Q: How does client-side verification work? A: The client SDK stores a local copy of the latest verified Merkle tree root. On each read, it requests an inclusion proof from the server and verifies the hash chain locally, detecting any server-side tampering.

Q: What is the performance overhead of immutability? A: The Merkle tree adds a small hashing cost per transaction. Benchmarks show immudb handles millions of writes per second on modern hardware, making the overhead negligible for most workloads.

Sources

• https://github.com/codenotary/immudb
• https://immudb.io/docs/