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:

  1. Set (SetRequest) returns (TxMetadata)
  2. Get (KeyRequest) returns (Entry)
  3. SetReference (ReferenceRequest) returns (TxMetadata)
  5. Scan(ScanRequest) returns (Entries)
  6. History(HistoryRequest) returns (Entries)
  8. // grouping and sorting keys based on assgined scores
  9. ZAdd (ZAddRequest) returns (TxMetadata)
  10. ZScan (ZScanRequest) returns (ZEntries)

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

  1. TxById(TxRequest) returns (Tx)
  2. TxScan(TxScanRequest) returns (TxList)

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

  1. VerifiableSet (VerifiableSetRequest) returns (VerifiableTx)
  2. VerifiableGet (VerifiableGetRequest) returns (VerifiableEntry)
  4. VerifiableTxById(VerifiableTxRequest) returns (VerifiableTx)
  6. VerifiableSetReference (VerifiableReferenceRequest) returns (VerifiableTx)
  8. 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.

  1. SQLExec(SQLExecRequest) returns (SQLExecResult)
  2. SQLQuery(SQLQueryRequest) returns (SQLQueryResult)
  3. ​
  4. 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:

  1. export IMMUDB_S3_STORAGE=true
  2. export IMMUDB_S3_ACCESS_KEY_ID=<S3 ACCESS KEY ID>
  3. export IMMUDB_S3_SECRET_KEY=<SECRET KEY>
  4. export IMMUDB_S3_BUCKET_NAME=<BUCKET NAME>
  5. export IMMUDB_S3_PATH_PREFIX=testing-001
  6. export IMMUDB_S3_ENDPOINT="https://${IMMUDB_S3_BUCKET_NAME}.s3.amazonaws.com"
  8. ./immudb