Reading and inserting data

The format for writing data is the same in both Set and VerifiedSet, as is the same for reading data in both Get and VerifiedGet.

The only difference is that VerifiedSet returns proofs needed to mathematically verify that the data was not tampered. Note that generating that proof has a slight performance impact, so primitives are allowed without the proof. It is still possible get the proofs for a specific item at any time, so the decision about when or how frequently to do checks (with the Verify version of a method) is completely up to the user. It's possible also to use dedicated auditors to ensure the database consistency, but the pattern in which every client is also an auditor is the more interesting one.

Get and Set

tx, err = client.Set(ctx, []byte(`hello`), []byte(`immutable world`))
if  err != nil {
    log.Fatal(err)
}

fmt.Printf("Successfully committed tx %d\n", tx.Id)

entry, err := client.Get(ctx, []byte(`hello`))
if  err != nil {
    log.Fatal(err)
}

fmt.Printf("Successfully retrieved entry: %v\n", entry)

String key = "key1";
byte[] value = new byte[]{1, 2, 3};

try {
    immuClient.set(key, value);
} catch (CorruptedDataException e) {
    // ...
}

try {
    value = immuClient.get(key);
} catch (Exception e) {
    // ...
}

Note that value is a primitive byte array. You can set the value of a String using:
"some string".getBytes(StandardCharsets.UTF_8)

Also, set method is overloaded to allow receiving the key parameter as a byte[] data type.

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

import ImmudbClient from 'immudb-node'
import Parameters from 'immudb-node/types/parameters'

const IMMUDB_HOST = '127.0.0.1'
const IMMUDB_PORT = '3322'
const IMMUDB_USER = 'immudb'
const IMMUDB_PWD = 'immudb'

const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

(async () => {
    await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })

    const setReq: Parameters.Set = { key: 'hello', value: 'world' }
    const setRes = await cl.set(setReq)
    console.log('success: set', setRes)

    const getReq: Parameters.Get = { key: 'hello' }
    const getRes = await cl.get(getReq)
    console.log('success: get', getRes)
})()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.

Get at and since a transaction

You can retrieve a key on a specific transaction with VerifiedGetAt and since a specific transaction with VerifiedGetSince.

ventry, err = client.VerifiedGetAt(ctx, []byte(`key`), meta.Id)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Successfully retrieved entry at %v with value %s\n", ventry.Tx, ventry.Value)

ventry, err = client.VerifiedGetSince(ctx, []byte(`key`), 4)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Successfully retrieved entry at %v with value %s\n", ventry.Tx, ventry.Value)

byte[] key = "key1".getBytes(StandardCharsets.UTF_8);
byte[] val = new byte[]{1, 2, 3, 4, 5};
TxMetadata txMd = null;

try {
    txMd = immuClient.set(key, val);
} catch (CorruptedDataException e) {
    // ...
}

// The standard (traditional) get options:

KV kv = immuClient.getAt(key, txMd.id);

kv = immuClient.getSince(key, txMd.id);

// The verified get flavours:

Entry vEntry = null;
try {
    vEntry = immuClient.verifiedGetAt(key, vEntry.txId);
} catch (VerificationException e) {
    // ...
}

try {
    vEntry = immuClient.verifiedGetSince(key, vEntry.txId);
} catch (VerificationException e) {
    // ...
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

import ImmudbClient from 'immudb-node'
import Parameters from 'immudb-node/types/parameters'

const IMMUDB_HOST = '127.0.0.1'
const IMMUDB_PORT = '3322'
const IMMUDB_USER = 'immudb'
const IMMUDB_PWD = 'immudb'

const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

(async () => {
    await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
    const { id } = await cl.set({ key: 'key', value: 'value' })

    const verifiedGetAtReq: Parameters.VerifiedGetAt = {
        key: 'key',
        attx: id
    }
    const verifiedGetAtRes = await cl.verifiedGetAt(verifiedGetAtReq)
    console.log('success: verifiedGetAt', verifiedGetAtRes)

    for (let i = 0; i < 4; i++) {
        await cl.set({ key: 'key', value: `value-${i}` })
    }

    const verifiedGetSinceReq: Parameters.VerifiedGetSince = {
        key: 'key',
        sincetx: 2
    }
    const verifiedGetSinceRes = await cl.verifiedGetSince(verifiedGetSinceReq)
    console.log('success: verifiedGetSince', verifiedGetSinceRes)
})()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.

Retrieving transactions by ID

It's possible to retrieve all the keys inside a specific transaction.

setRequest := &schema.SetRequest{KVs: []*schema.KeyValue{
    {Key: []byte("key1"), Value: []byte("val1")},
    {Key: []byte("key2"), Value: []byte("val2")},
}}

meta, err := client.SetAll(ctx, setRequest)
if err != nil {
    log.Fatal(err)
}

tx , err := client.TxByID(ctx, meta.Id)
if err != nil {
    log.Fatal(err)
}

for _, entry := range tx.Entries {
    item, err := client.VerifiedGetAt(ctx, entry.Key, meta.Id)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("retrieved key %s and val %s\n", item.Key, item.Value)
}

TxMetadata txMd = null;
try {
    txMd = immuClient.verifiedSet(key, val);
} catch (VerificationException e) {
    // ...
}
try {
    Tx tx = immuClient.txById(txMd.id);
} catch (MaxWidthExceededException | NoSuchAlgorithmException e) {
    // ...
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

import ImmudbClient from 'immudb-node'
import Parameters from 'immudb-node/types/parameters'

const IMMUDB_HOST = '127.0.0.1'
const IMMUDB_PORT = '3322'
const IMMUDB_USER = 'immudb'
const IMMUDB_PWD = 'immudb'

const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

(async () => {
    await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
    const { id } = await cl.set({ key: 'key', value: 'value' })

    const txByIdReq: Parameters.TxById = { tx: id }
    const txByIdRes = await cl.txById(txByIdReq)
    console.log('success: txById', txByIdRes)
})()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.

Retrieving verified transactions by ID

It's possible to retrieve all the keys inside a specific verified transaction.

setRequest := &schema.SetRequest{KVs: []*schema.KeyValue{
    {Key: []byte("key1"), Value: []byte("val1")},
    {Key: []byte("key2"), Value: []byte("val2")},
}}

meta, err := client.SetAll(ctx, setRequest)
if err != nil {
    log.Fatal(err)
}

tx , err := client.VerifiedTxByID(ctx, meta.Id)
if err != nil {
    log.Fatal(err)
}

for _, entry := range tx.Entries {
    item, err := client.VerifiedGetAt(ctx, entry.Key, meta.Id)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("retrieved key %s and val %s\n", item.Key, item.Value)
}

TxMetadata txMd = null;
try {
    txMd = immuClient.verifiedSet(key, val);
} catch (VerificationException e) {
    // ...
}
try {
    Tx tx = immuClient.verifiedTxById(txMd.id);
} catch (VerificationException e) {
    // ...
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

import ImmudbClient from 'immudb-node'
import Parameters from 'immudb-node/types/parameters'

const IMMUDB_HOST = '127.0.0.1'
const IMMUDB_PORT = '3322'
const IMMUDB_USER = 'immudb'
const IMMUDB_PWD = 'immudb'

const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

(async () => {
    await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
    const { id } = await cl.set({ key: 'key', value: 'value' })
    
    const verifiedTxByIdReq: Parameters.VerifiedTxById = { tx: id }
    const verifiedTxByIdRes = await cl.verifiedTxByID(verifiedTxByIdReq)
    console.log('success: verifiedTxByID', verifiedTxByIdRes)
})()

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.

Retrieving transactions by ID with filters

The transaction entries are generated by writing key-value pairs, referencing keys, associating scores to key-value pairs (with ZAdd operation), and by mapping SQL data model into key-value model.

With TxByIDWithSpec operation it's possible to retrieve entries of certain types, either retrieving the digest of the value assigned to the key (EntryTypeAction_ONLY_DIGEST), the raw value (EntryTypeAction_RAW_VALUE) or the structured value (EntryTypeAction_RESOLVE).

// fetch kv and sorted-set entries as structured values while skipping sql-related entries
tx , err := client.TxByIDWithSpec(ctx, &schema.TxRequest{
                Tx: hdr.Id,
                EntriesSpec: &schema.EntriesSpec{
                    KvEntriesSpec: &schema.EntryTypeSpec{
                        Action: schema.EntryTypeAction_RESOLVE,
                    },
                    ZEntriesSpec: &schema.EntryTypeSpec{
                        Action: schema.EntryTypeAction_RESOLVE,
                    },
                    // explicit exclusion is optional
                    SqlEntriesSpec: &schema.EntryTypeSpec{
                        // resolution of sql entries is not supported
                        Action: schema.EntryTypeAction_EXCLUDE,
                    },
                },
            }))
if err != nil {
    log.Fatal(err)
}

for _, entry := range tx.KvEntries {
   fmt.Printf("retrieved key %s and val %s\n", entry.Key, entry.Value)
}

for _, entry := range tx.ZEntries {
   fmt.Printf("retrieved set %s key %s and score %v\n", entry.Set, entry.Key, entry.Score)
}

// scan over unresolved entries
// either EntryTypeAction_ONLY_DIGEST or EntryTypeAction_RAW_VALUE options
for _, entry := range tx.Entries {
   fmt.Printf("retrieved key %s and digest %v\n", entry.Key, entry.HValue)
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.

Conditional writes

Immudb can check additional preconditions before the write operation is made. Precondition is checked atomically with the write operation. It can be then used to ensure consistent state of data inside the database.

Following preconditions are supported:

• MustExist - precondition checks if given key exists in the database, this precondition takes into consideration logical deletion and data expiration, if the entry was logically deleted or has expired, MustExist precondition for such entry will fail
• MustNotExist - precondition checks if given key does not exist in the database, this precondition also takes into consideration logical deletion and data expiration, if the entry was logically deleted or has expired, MustNotExist precondition for such entry will succeed
• NotModifiedAfterTX - precondition checks if given key was not modified after given transaction id, local deletion and setting entry with expiration data is also considered modification of the entry

In many cases, keys used for constraints will be the same as keys for written entries. A good example here is a situation when a value is set only if that key does not exist. This is not strictly required - keys used in constraints do not have to be the same or even overlap with keys for modified entries. An example would be if only one of two keys should exist in the database. In such case, the first key will be modified and the second key will be used for MustNotExist constraint.

A write operation using precondition can not be done in an asynchronous way. Preconditions are checked twice when processing such requests - first check is done against the current state of internal index, the second check is done just before persisting the write and requires up-to-date index.

Preconditions are available on SetAll, Reference and ExecAll operations.

In go sdk, the schema package contains convenient wrappers for creating constraint objects, such as schema.PreconditionKeyMustNotExist.

package main

import (
	"context"
	"log"

	"github.com/codenotary/immudb/pkg/api/schema"
	immudb "github.com/codenotary/immudb/pkg/client"
	immuerrors "github.com/codenotary/immudb/pkg/client/errors"
)

func main() {
	opts := immudb.DefaultOptions().
		WithAddress("localhost").
		WithPort(3322)

	client := immudb.NewClient().WithOptions(opts)
	err := client.OpenSession(
		context.TODO(),
		[]byte(`immudb`),
		[]byte(`immudb`),
		"defaultdb",
	)
	if err != nil {
		log.Fatal(err)
	}

	defer client.CloseSession(context.TODO())

	_, err = client.Set(context.TODO(), []byte("key"), []byte("value"))
	if err != nil {
		log.Fatal(err)
	}

	// ensure modification is done atomically when there are concurrent writers

	entry, err := client.Get(context.TODO(), []byte("key"))
	if err != nil {
		log.Fatal(err)
	}

	_, err = client.SetAll(
		context.TODO(),
		&schema.SetRequest{
			KVs: []*schema.KeyValue{{
				Key:   []byte("key"),
				Value: []byte("value2"),
			}},
			Preconditions: []*schema.Precondition{
				schema.PreconditionKeyNotModifiedAfterTX(
					[]byte("key"),
					entry.Tx,
				),
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	// allow setting the key only once

	_, err = client.SetAll(context.TODO(), &schema.SetRequest{
		KVs: []*schema.KeyValue{
			{Key: []byte("key-once"), Value: []byte("val")},
		},
		Preconditions: []*schema.Precondition{
			schema.PreconditionKeyMustNotExist([]byte("key-once")),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	// set only one key in a group of keys

	_, err = client.SetAll(context.TODO(), &schema.SetRequest{
		KVs: []*schema.KeyValue{
			{Key: []byte("key-group-1"), Value: []byte("val1")},
		},
		Preconditions: []*schema.Precondition{
			schema.PreconditionKeyMustNotExist([]byte("key-group-2")),
			schema.PreconditionKeyMustNotExist([]byte("key-group-3")),
			schema.PreconditionKeyMustNotExist([]byte("key-group-4")),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	// check if returned error indicates precondition failure

	_, err = client.SetAll(context.TODO(), &schema.SetRequest{
		KVs: []*schema.KeyValue{
			{Key: []byte("key-missing"), Value: []byte("val")},
		},
		Preconditions: []*schema.Precondition{
			schema.PreconditionKeyMustExist([]byte("key-missing")),
		},
	})
	immuErr := immuerrors.FromError(err)
	if immuErr != nil &&
		immuErr.Code() == immuerrors.CodIntegrityConstraintViolation {
		log.Println("Constraint validation failed")
	}

}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.