# Immudb — Immutable Database with Cryptographic Verification

> Tamper-proof database built on a Merkle tree that provides cryptographic proof of data integrity for audit logs, financial records, and compliance workflows.

## Install

Save as a script file and run:

# Immudb — Immutable Database with Cryptographic Verification

## Quick Use
```bash
docker run -d --name immudb -p 3322:3322 -p 9497:9497 codenotary/immudb
# Connect with the CLI client
docker run -it --rm --network host codenotary/immuclient login immudb
```

## 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/

---
Source: https://tokrepo.com/en/workflows/69ecfc3a-3d3a-11f1-9bc6-00163e2b0d79
Author: Script Depot