coreimmudb

CoreImmuDB Package Guide

Steps for connecting to Immudb

• The package provides three methods to establish a database connection. If an error occurs during the connection establishment then error is returned.

1. coreimmudb.InitUsingJson() - Provide JSON file path to read ImmuDB config details.
   

   [
   	{
   		"hostName": "ImmuDbHost1",
   		"server": "127.0.0.1",
   		"port": 3322,
   		"database": "defaultdb",
   		"username": "immudb",
   		"password": "immudb",
   		"dir": "",
   		"maxRecvMsgSize: 4,
   		"isDefault": true,
   		"isDisabled": false
   		}
   ]
   

2. coreimmudb.InitImmuDBConnections() - Provide Immudb config details in []coreimmudb.ImmuHost

   [
   		coreimmudb.ImmuHost{
   			"HostName": "ImmuDbHost1",
   			"Server": "127.0.0.1",
   			"Port": 3322,
   			"database": "defaultdb",
   			"Username": "immudb",
   			"Password": "immudb",
   			"Dir": "",
   			"MaxRecvMsgSize": 4,
   			"IsDefault": true,
   			"IsDisabled": false
   		}
   ]
   

3. coreimmudb.AddDBConnection - Provide Immudb connection details using coreimmudb.ImmuHost

   		coreimmudb.ImmuHost{
   			"HostName": "ImmuDbHost1",
   			"Server": "127.0.0.1",
   			"Port": 3322,
   			"database": "defaultdb",
   			"Username": "immudb",
   			"Password": "immudb",
   			"Dir": "",
   			"MaxRecvMsgSize": 4,
   			"IsDefault": true,
   			"IsDisabled": false
   		}
   
   

   Parameters
   

   Hostname (hostName) - Hostname for the database connection.
   Server (server) - Database server address.
   Port (port) - Port on which ImmuDB running.
   Database (database) - Database name.
   Username (username) - Database username
   Password (password) - Database password
   Dir (dir) - Storing .identity (database server identity) and .state file
   MaxRecvMsgSize (maxRecvMsgSize) - Recieve message maximum size in MB (Default: 4MB)
   IsDefault (isDefault) - Default database selection
   IsDisabled (isDisabled) - Skip connection
   
   

Disconnecting ImmuDB connection

Use DeleteImmuDbSession() function to disconnect ImmuDB connection.
coreimmudb.DeleteImmuDbSession(hostName string)

• Pass hostname as argument to the above method.
• It will return error, if failed to disconnect ImmuDB.
  

Get Immudb client for specific Hostname

Use GetImmuDbConnection() function to get ImmuDB client.
coreimmudb.GetImmuDbConnection(hostName string)

• Pass hostname as argument to the above method.
• It returns immudb client if there are no errors else it returns an error.
  
  

Create Database

Use CreateDatabase() method to create database with specific database settings.
(i *ImmuDAO) coreimmudb.CreateDatabase(dbName string, dbSettings *schema.DatabaseNullableSettings)

• Pass dbName and dbSettings as argument to the above method.
• It returns (*schema.CreateDatabaseResponse, error) - If no error then it returns *schema.CreateDatabaseResponse or else an error.
  
  

Create Database User

Use CreateUser() method to create user with specific permission for a database.
(i *ImmuDAO) coreimmudb.CreateUser(username, password, dbName string, permission int)

• Pass username, password, dbName and permission as argument to the above method.
• It returns error - If password criteria not matched or database doesn't exists or user already exists or else the user gets created.
  
  

Read Operations

Get Options

coreimmudb.GetOptions{} is used to set additional options when reading a value with a Get call.

{
	"atTx": 4,
	"sinceTx": 0,
	"noWait": True,
	"atRevision": 0
}

AtTx (atTx) - This option is used to specify that the value read must be the one set at transaction with id given in the tx parameter.
SinceTx (sinceTx) - This option can be used to avoid waiting for the indexer to be up-to-date with the most recent transaction.
NoWait (noWait) - If this option set to true, then the server will not wait for the indexer to be up-to-date with the most recent transaction.

• This means that the user will get the result instantly without the risk of the server wait for the indexer that may happen in case of a large spike of new transactions.
  

AtRevision (atRevision) - This option is used to request specific revision for given key.

• The way revision is interpreted depends on the value:
  • if rev = 0, returns current value.
    
  • if rev > 0, returns nth revision value.
    
  • if rev < 0, returns nth revision value from the end.
    

Combination of coreimmudb.GetOptions which will work together.

Note :- These Options only work with GetKeyData() and GetVerifiedKeyData() and does not work with GetAllKeysData() and GetKeyHistory().

Get key data

Use GetKeyData() method to fetch data for key.
(i *ImmuDAO) coreimmudb.GetKeyData(key []byte)

• Pass key as argument to the above method.
• It returns (*schema.Entry, error) - If no error then it returns *schema.Entry or else an error.
  
  

Get key data with additional server-provided proof validation

Use GetVerifiedKeyData() method to fetch data for key with additional server-provided proof validation.
(i *ImmuDAO) coreimmudb.GetVerifiedKeyData(key []byte)

• Pass key as argument to the above method.
• It returns (*schema.Entry, error)- If no error then it returns *schema.Entry or else an error.
  
  

Get data for all provided keys

Use GetAllKeysData() method to fetch data for all provided keys.
(i *ImmuDAO) coreimmudb.GetAllKeysData(keys [][]byte)

• Pass arrays of keys as argument to the above method.
• It returns (*schema.Entries, error) - If no error then it returns *schema.Entries or else an error.
  
  

Get history for single key

Use GetKeyHistory() method to get history(all values) of a key.
(i *ImmuDAO) GetKeyHistory(key []byte, offset uint64, limit int32, desc bool)

• Pass Key, offset, limit, desc as argument to the above method.
• It returns (*schema.Entries, error) - If no error then it returns *schema.Entries or else an error.
  
  

Write Operations

Set key and value

Use SetKeyData() method to set value against key.
(i *ImmuDAO) coreimmudb.SetKeyData(key, value []byte)

• Pass key and value as argument to the above method.
• It returns (*schema.TxHeader, error) - If no error then it returns *schema.TxHeader or else an error.
  
  

Set key and value with additional server-provided proof validation

Use SetVerifiedKeyData() method to set value against key with additional server-provided proof validation..
(i *ImmuDAO) coreimmudb.SetVerifiedKeyData(key, value []byte)

• Pass key and value as argument to the above method.
• It returns (*schema.TxHeader, error) - If no error then it returns *schema.TxHeader or else an error.
  
  

Set multiple key and value pairs

Use SetAllKeysData() method to set multiple key, value pairs.
(i *ImmuDAO) coreimmudb.SetAllKeysData(kv []KeyValue)

• Pass array of key and value as argument to the above method.
• It returns (*schema.TxHeader, error) - If no error then it returns *schema.TxHeader or else an error.
  
  

Set key and value with expiry time

Use ExpirableKeySet() method to set value against key with expiration time.
(i *ImmuDAO) coreimmudb.ExpirableKeySet(key, value []byte, expiresAt time.Time)

• Pass key, value and expiresAt as argument to the above method.
• It returns (*schema.TxHeader, error) - If no error then it returns *schema.TxHeader or else an error.
  
  

Delete Operations

Logically(soft) delete key and value

Use DeleteKey() method to soft delete key and its associated value.
(i *ImmuDAO) coreimmudb.DeleteKey(keys [][]byte)

• Pass array of keys as argument to the above method.
• It returns (*schema.TxHeader, error) - If no error then it returns *schema.TxHeader or else an error.
  
  

Delete Database

Use DeleteDatabase() method to remove database from ImmuDB.
(i *ImmuDAO) coreimmudb.DeleteDatabase(dbName string)

• Pass dbName as argument to the above method.
• It returns (*schema.DeleteDatabaseResponse, error) - If no error then it returns *schema.DeleteDatabaseResponse or else an error.