Transactions

GetAll, SetAll and ExecAll are the foundation of transactions in immudb. They allow the execution of a group of commands in a single step, with two important guarantees:

  • All the commands in a transaction are serialized and executed sequentially. No request issued by another client can ever interrupt the execution of a transaction. This guarantees that the commands are executed as a single isolated operation.
  • Either all of the commands are processed, or none are, so the transaction is also atomic.

GetAll

  1.     itList, err := db.GetAll( [][]byte{
  2.             []byte("key1"),
  3.             []byte("key2"),
  4.             []byte("key3"),
  5.         })
  1. // Using getAll:
  2. List<String> keys = Arrays.asList("key1", "key2", "key3");
  3. List<KV> got = immuClient.getAll(keys);
  5. // Using execAll for setting multiple KVs at once:
  6. byte[] item1 = "execAll_key1".getBytes(StandardCharsets.UTF_8);
  7. byte[] item2 = "execAll_key2".getBytes(StandardCharsets.UTF_8);
  9. immuClient.execAll(
  10.         Arrays.asList(                  // Providing just a kvList, which is a List< Pair<byte[], byte[]> >.
  11.                 Pair.of(item1, item1),
  12.                 Pair.of(item2, item2)
  13.         ),
  14.         null,                          // No refList provided.
  15.         null                           // No zaddList provided.
  16. );
  18. // Using execAll for setting multiple references and doing zAdd(s):
  19. immuClient.execAll(
  20.         null,                          // No kvList provided.
  21.         Arrays.asList(                 // The refList.
  22.                 Pair.of("ref1".getBytes(StandardCharsets.UTF_8), item1),
  23.                 Pair.of("ref2".getBytes(StandardCharsets.UTF_8), item2)
  24.         ),
  25.         // The zaddList.
  26.         Collections.singletonList(Triple.of("set1", 1.0, "execAll_key1"))
  27. );

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 projectTransactions - 图1 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const getAllReq: Parameters.GetAll = {
  15.         keysList: ['key1', 'key2', 'key3'],
  16.         sincetx: 0
  17.     }
  18.     const getAllRes = await cl.getAll(getAllReq)
  19.     console.log('success: getAll', getAllRes)
  20. })()

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 projectTransactions - 图2 (opens new window)

If you’re using another development language, please read up on our immugwTransactions - 图3 (opens new window) option.

SetAll

A more versatile atomic multi set operation

SetBatch and GetBatch example

  1.     kvList := &schema.KVList{KVs: []*schema.KeyValue{
  2.         {Key: []byte("1,2,3"), Value: []byte("3,2,1")},
  3.         {Key: []byte("4,5,6"), Value: []byte("6,5,4")},
  4.     }}
  6.     _, err = client.SetAll(ctx, kvList)
  1. List<KV> kvs = Arrays.asList(
  2.     new KVPair("key1", "val1".getBytes(StandardCharsets.UTF_8)),
  3.     new KVPair("key2", "val2".getBytes(StandardCharsets.UTF_8)),
  4. );
  6. KVList kvList = KVList.newBuilder().addAll(kvs).build();
  7. try {
  8.     immuClient.setAll(kvList);
  9. } catch (CorruptedDataException e) {
  10.     // ...
  11. }

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 projectTransactions - 图4 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const setAllReq: Parameters.SetAll = {
  15.         kvsList: [
  16.             { key: '1,2,3', value: '3,2,1' },
  17.             { key: '4,5,6', value: '6,5,4' },
  18.         ]
  19.     }
  20.     const setAllRes = await cl.setAll(setAllReq)
  21.     console.log('success: setAll', setAllRes)
  22. })()

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 projectTransactions - 图5 (opens new window)

If you’re using another development language, please read up on our immugwTransactions - 图6 (opens new window) option.

ExecAll

ExecAll permits many insertions at once. The difference is that is possible to specify a list of a mix of key value set, reference and zAdd insertions. The argument of a ExecAll is an array of the following types:

  • Op_Kv: ordinary key value item
  • Op_ZAdd: ZAdd option element
  • Op_Ref: Reference option element

It’s possible to persist and reference items that are already persisted on disk. In that case is mandatory to provide the index of the referenced item. This has to be done for:

  • Op_ZAdd
  • Op_Ref If zAdd or reference is not yet persisted on disk it’s possible to add it as a regular key value and the reference is done onFly. In that case if BoundRef is true the reference is bounded to the current transaction values.
  1.         aOps := &schema.ExecAllRequest{
  2.             Operations: []*schema.Op{
  3.                 {
  4.                     Operation: &schema.Op_Kv{
  5.                         Kv: &schema.KeyValue{
  6.                             Key:   []byte(`notPersistedKey`),
  7.                             Value: []byte(`notPersistedVal`),
  8.                         },
  9.                     },
  10.                 },
  11.                 {
  12.                     Operation: &schema.Op_ZAdd{
  13.                         ZAdd: &schema.ZAddRequest{
  14.                             Set:   []byte(`mySet`),
  15.                             Score: 0.4,
  16.                             Key:   []byte(`notPersistedKey`)},
  17.                     },
  18.                 },
  19.                 {
  20.                     Operation: &schema.Op_ZAdd{
  21.                         ZAdd: &schema.ZAddRequest{
  22.                             Set:      []byte(`mySet`),
  23.                             Score:    0.6,
  24.                             Key:      []byte(`persistedKey`),
  25.                             AtTx:     idx.Id,
  26.                             BoundRef: true,
  27.                         },
  28.                     },
  29.                 },
  30.             },
  31.         }
  33.         idx , err = client.ExecAll(ctx, aOps)
  34.         if err != nil {
  35.             log.Fatal(err)
  36.         }
  37.         zscanOpts1 := &schema.ZScanRequest{
  38.             Set:     []byte(`mySet`),
  39.             SinceTx: math.MaxUint64,
  40.             NoWait: true,
  41.         }
  43.         list, err := client.ZScan(ctx, zscanOpts1)
  44.         if err != nil{
  45.             log.Fatal(err)
  46.         }
  47.         s, _ := json.MarshalIndent(list, "", "\t")
  48.         fmt.Print(string(s))
  1. byte[] item1 = "execAll_key1".getBytes(StandardCharsets.UTF_8);
  2. byte[] item2 = "execAll_key2".getBytes(StandardCharsets.UTF_8);
  4. // Using execAll just for setting multiple KVs:
  5. TxMetadata txMd = immuClient.execAll(
  6.         Arrays.asList(                 // The kvList.
  7.                 Pair.of(item1, item1),
  8.                 Pair.of(item2, item2)
  9.         ),
  10.         null,                         // No refList provided.
  11.         null                          // No zaddList provided.
  12. );
  14. immuClient.execAll(
  15.         null,                         // No kvList provided.
  16.         Arrays.asList(                // The refList.
  17.                 Pair.of("ref1".getBytes(StandardCharsets.UTF_8), item1),
  18.                 Pair.of("ref2".getBytes(StandardCharsets.UTF_8), item2)
  19.         ),
  20.         // The zaddList (even if it has one single entry).
  21.         Collections.singletonList(Triple.of("set1", 1.0, "execAll_key1"))
  22. );

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 projectTransactions - 图7 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     const { id } = await cl.set({ key: 'persistedKey', value: 'persistedVal' })
  16.     const setOperation = { kv: { key: 'notPersistedKey', value: 'notPersistedVal' } }
  17.     const zAddOperation = {
  18.         zadd: {
  19.             set: 'mySet',
  20.             score: 0.6,
  21.             key: 'notPersistedKey',
  22.             attx: 0,
  23.             boundref: true
  24.         }
  25.     }
  26.     const zAddOperation1 = {
  27.         zadd: {
  28.             set: 'mySet',
  29.             score: 0.6,
  30.             key: 'persistedKey',
  31.             attx: id,
  32.             boundref: true
  33.         }
  34.     }
  35.     const execAllReq: Parameters.ExecAll = {
  36.         operationsList: [
  37.             setOperation,
  38.             zAddOperation,
  39.             zAddOperation1,
  40.         ]
  41.     }
  42.     const execAllRes = await cl.execAll(execAllReq)
  43.     console.log('success: execAll', execAllRes)
  44. })()

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 projectTransactions - 图8 (opens new window)

If you’re using another development language, please read up on our immugwTransactions - 图9 (opens new window) option.

Tx Scan

TxScan permits iterating over transactions.

The argument of a TxScan is an array of the following types:

  • InitialTx: initial transaction id
  • Limit: number of transactions returned
  • Desc: order of returned transacations
  1.     _, err = client.Set(ctx, []byte("key1"), []byte("val1"))
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     _, err = client.Set(ctx, []byte("key2"), []byte("val2"))
  6.     if err != nil {
  7.         log.Fatal(err)
  8.     }
  9.     _, err = client.Set(ctx, []byte("key3"), []byte("val3"))
  10.     if err != nil {
  11.         log.Fatal(err)
  12.     }
  14.     txRequest := &schema.TxScanRequest{
  15.         InitialTx: 2,
  16.         Limit:     3,
  17.         Desc:      false,
  18.     }
  20.     txs , err := client.TxScan(ctx, txRequest)
  21.     if err != nil {
  22.         log.Fatal(err)
  23.     }
  25.     for _, tx := range txs.GetTxs() {
  26.         fmt.Printf("retrieved in ASC tx %d \n", tx.Metadata.Id )
  27.     }
  28.     txRequest = &schema.TxScanRequest{
  29.         InitialTx: 2,
  30.         Limit:     3,
  31.         Desc:      true,
  32.     }
  34.     txs , err = client.TxScan(ctx, txRequest)
  35.     if err != nil {
  36.         log.Fatal(err)
  37.     }

Then it’s possible to retrieve entries of every transactions:

  1.     for _, tx := range txs.GetTxs() {
  2.         for _, entry := range tx.Entries {
  3.             item, err := client.GetAt(ctx, entry.Key[1:], tx.Metadata.Id)
  4.             if err != nil {
  5.                 log.Fatal(err)
  6.             }
  7.             fmt.Printf("retrieved key %s and val %s\n", item.Key, item.Value)
  8.         }
  9.     }

Remember to strip the first byte in the key (key prefix). Remember that a transaction could contains sorted sets keys that should not be skipped.

  1. String key = "txtest-t2";
  2. byte[] val1 = "immuRocks!".getBytes(StandardCharsets.UTF_8);
  3. byte[] val2 = "immuRocks! Again!".getBytes(StandardCharsets.UTF_8);
  5. long initialTxId = 1;
  6. try {
  7.     TxMetadata txMd = immuClient.set(key, val1);
  8.     initialTxId = txMd.id;
  9.     txMd = immuClient.set(key, val2);
  10. } catch (CorruptedDataException e) {
  11.     Assert.fail("Failed at set.", e);
  12. }
  13.             // This is a .txScan(initialTxId, limit, desc)
  14. List<Tx> txs = immuClient.txScan(initialTxId, 1, false);
  15. // We expect one Tx entry in this list.
  17. txs = immuClient.txScan(initialTxId, 2, false);
  18. // We expect two Tx entries in this list.

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 projectTransactions - 图10 (opens new window)

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  4. const IMMUDB_HOST = '127.0.0.1'
  5. const IMMUDB_PORT = '3322'
  6. const IMMUDB_USER = 'immudb'
  7. const IMMUDB_PWD = 'immudb'
  9. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  11. (async () => {
  12.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  14.     for (let i = 0; i < 3; i++) {
  15.         await cl.set({ key: `key${i}`, value: `val${i}` })
  16.     }
  18.     const txScanReq: Parameters.TxScan = {
  19.         initialtx: 2,
  20.     limit: 3,
  21.     desc: false
  22.     }
  23.     const txScanRes = await cl.txScan(txScanReq)
  24.     console.log('success: txScan', txScanRes)
  25. })()

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 projectTransactions - 图11 (opens new window)

If you’re using another development language, please read up on our immugwTransactions - 图12 (opens new window) option.