# immudb specs

immudb is an append-only, tamperproof database with key/value and SQL (Structured Query Language) application programming interfaces.

The immudb core persistence layer consists of a cryptographically-immutable log. Transactions are sequentially stored and uniquely identified by unsigned 64-bit integer values, thus setting a theoretical limit of 18446744073709551615 transactions (1^64 - 1).

In order to provide manageable limits, immudb is designed to set an upper bound to the number of key-value pairs included in a single transaction. The default value being 1024, so using default settings, the theoretical number of key-value pairs that can be stored in immudb is: 1024 * (1^64 - 1).

We designed immudb to require stable resources but not imposing strong limitations as most of the settings can be adjusted based on the use-case requirements.

While key-value pairs consist of arbitrary byte arrays, a maximum length may be set at database creation time. Both parameters can be increased as needed, considering:

  • long keys may degrade performance (when querying data through the index)
  • longer values requires more memory at runtime

Note: The cryptographic linking does not impose a practical restriction.

immudb relies on a file abstraction layer and does not directly interact with the underlying file-system, if any. But default storage layer implementation writes data into fixed-size files, default size being 512MB. The current theoretical maximum number of files is 100 millions.

# Summary

Theoretical limits may be determined by a couple of elements:

  • max number transactions: 2^64-1 (uint64)
  • max number of files: 2^63-1 (max file size 2^56-1)
  • max value length: 32 MB (max size: 2^56-1 bytes)
  • max key length: 1024 Bytes (max length: 2^31-1 bytes)

# Running platforms

immudb server runs in most operating systems: BSD, Linux, OS X, Solaris, Windows, IBM z/OS

# Key/Value API

immudb includes a basic yet complete set of operations you would expect from a key-value store:

Set (SetRequest) returns (TxMetadata)
Get (KeyRequest) returns (Entry)
SetReference (ReferenceRequest) returns (TxMetadata)

Scan(ScanRequest) returns (Entries)
History(HistoryRequest) returns (Entries)

// grouping and sorting keys based on assgined scores
ZAdd (ZAddRequest) returns (TxMetadata)
ZScan (ZScanRequest) returns (ZEntries)

Additionally, immudb exposes direct access to transactions based on its unique identifier:

TxById(TxRequest) returns (Tx)
TxScan(TxScanRequest) returns (TxList)

But more importantly, immudb is able to generate cryptographic-proofs whenever is needed:

VerifiableSet (VerifiableSetRequest) returns (VerifiableTx)
VerifiableGet (VerifiableGetRequest) returns (VerifiableEntry)

VerifiableTxById(VerifiableTxRequest) returns (VerifiableTx)

VerifiableSetReference (VerifiableReferenceRequest) returns (VerifiableTx)

VerifiableZAdd (VerifiableZAddRequest) returns (VerifiableTx)

Check official SDKs documentation at develop with immudb.

# SQL API

Based on the key-value storage layer, immudb includes a simplified SQL engine which is able to interprete most common features you would expect from a relational database but with the possibility to verify rows has not been tampered with.

SQLExec(SQLExecRequest) returns (SQLExecResult)
SQLQuery(SQLQueryRequest) returns (SQLQueryResult)VerifiableSQLGet (VerifiableSQLGetRequest) returns (VerifiableSQLEntry)

Check SQL reference for a comprehensive description of SQL statements.

# S3 Storage Backend

immudb can store its data in the Amazon S3 service (or a compatible alternative). The following example shows how to run immudb with the S3 storage enabled:

export IMMUDB_S3_STORAGE=true
export IMMUDB_S3_ACCESS_KEY_ID=<S3 ACCESS KEY ID>
export IMMUDB_S3_SECRET_KEY=<SECRET KEY>
export IMMUDB_S3_BUCKET_NAME=<BUCKET NAME>
export IMMUDB_S3_LOCATION=<AWS S3 REGION>
export IMMUDB_S3_PATH_PREFIX=testing-001
export IMMUDB_S3_ENDPOINT="https://${IMMUDB_S3_BUCKET_NAME}.s3.amazonaws.com"

./immudb