Management operations

User management

User management is exposed with following methods:

  • CreateUser
  • ChangePermission
  • ChangePassword

Password must have between 8 and 32 letters, digits and special characters of which at least 1 uppercase letter, 1 digit and 1 special character.

Admin permissions are:

  • PermissionSysAdmin = 255
  • PermissionAdmin = 254

Non-admin permissions are:

  • PermissionNone = 0
  • PermissionR = 1
  • PermissionRW = 2
  1.     client, err := c.NewImmuClient(c.DefaultOptions())
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     ctx := context.Background()
  6.     lr , err := client.Login(ctx, []byte(`immudb`), []byte(`immudb`))
  8.     md := metadata.Pairs("authorization", lr.Token)
  9.     ctx = metadata.NewOutgoingContext(context.Background(), md)
  11.     err = client.CreateUser(ctx, []byte(`myNewUser1`), []byte(`myS3cretPassword!`), auth.PermissionR, "defaultdb")
  12.     if err != nil {
  13.         log.Fatal(err)
  14.     }
  15.     err = client.ChangePermission(ctx, schema.PermissionAction_GRANT, "myNewUser1", "defaultDB",  auth.PermissionRW)
  16.     if err != nil {
  17.         log.Fatal(err)
  18.     }
  19.     err = client.ChangePassword(ctx, []byte(`myNewUser1`), []byte(`myS3cretPassword!`), []byte(`myNewS3cretPassword!`))
  20.     if err != nil {
  21.         log.Fatal(err)
  22.     }
  1. String database = "defaultdb";
  2. String username = "testCreateUser";
  3. String password = "testTest123!";
  4. Permission permission = Permission.PERMISSION_RW;
  6. immuClient.login("immudb", "immudb");
  7. immuClient.useDatabase(database);
  9. try {
  10.     immuClient.createUser(username, password, permission, database);
  11. } catch (StatusRuntimeException e) {
  12.     System.out.println("createUser exception: " + e.getMessage());
  13. }
  15. // We expect getting back the previously created "testCreateUser" user.
  16. System.out.println("listUsers:");
  17. List<User> users = immuClient.listUsers();
  18. users.forEach(user -> System.out.println("\t- " + user));
  20. // Changing the user password.
  21. immuClient.changePassword(username, password, "newTestTest123!");

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

  1. import ImmudbClient from 'immudb-node'
  2. import Parameters from 'immudb-node/types/parameters'
  3. import { USER_ACTION, USER_PERMISSION } from 'immudb-node/dist/types/user'
  5. const IMMUDB_HOST = '127.0.0.1'
  6. const IMMUDB_PORT = '3322'
  7. const IMMUDB_USER = 'immudb'
  8. const IMMUDB_PWD = 'immudb'
  10. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  12. (async () => {
  13.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  15.     const createUserRequest: Parameters.CreateUser = {
  16.         user: 'myNewUser1',
  17.         password: 'myS3cretPassword!',
  18.         permission: USER_PERMISSION.READ_ONLY,
  19.         database: 'defaultdb',
  20.     };
  21.     const createUserRes = cl.createUser(createUserRequest)
  22.     console.log('success: createUser', createUserRes)
  24.     const changePermissionReq: Parameters.ChangePermission = {
  25.         action: USER_ACTION.GRANT,
  26.         username: 'myNewUser1',
  27.         database: 'defaultDB',
  28.         permission: USER_PERMISSION.READ_WRITE
  29.     }
  30.     const changePermissionRes = await cl.changePermission(changePermissionReq)
  31.     console.log('success: changePermission', changePermissionRes)
  33.     const changePasswordReq: Parameters.ChangePassword = {
  34.         user: 'myNewUser1',
  35.         oldpassword: 'myS3cretPassword!',
  36.         newpassword: 'myNewS3cretPassword!'
  37.     }
  38.     const changePasswordRes = await cl.changePassword(changePasswordReq)
  39.     console.log('success: changePassword', changePermissionRes)
  40. })()

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

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

Multiple databases

Starting with version 0.7.0 of immudb, we introduced multi-database support. By default, the first database is either called defaultdb or based on the environment variable IMMUDB_DBNAME. Handling users and databases requires the appropriate privileges. Users with PermissionAdmin can control everything. Non-admin users have restricted permissions and can read or write only their databases, assuming sufficient privileges.

Each database has default MaxValueLen and MaxKeyLen values. These are fixed respectively to 1MB and 1KB. These values at the moment are not exposed to client SDK and can be modified using internal store options.

This example shows how to create a new database and how to write records to it. To create a new database, use CreateDatabase method. To write into a specific database an authenticated context is required. Start by calling the UseDatabase method to obtain a token. A token is used for both authorization and routing commands to a specific database. To set up an authenticated context, it’s sufficient to put a token inside metadata.

  1.     client, err := c.NewImmuClient(c.DefaultOptions())
  2.     if err != nil {
  3.         log.Fatal(err)
  4.     }
  5.     ctx := context.Background()
  6.     lr , err := client.Login(ctx, []byte(`immudb`), []byte(`immudb`))
  8.     md := metadata.Pairs("authorization", lr.Token)
  9.     ctx = metadata.NewOutgoingContext(context.Background(), md)
  11.     err = client.CreateDatabase(ctx, &schema.Database{
  12.         Databasename: "myimmutabledb",
  13.     })
  14.     if err != nil {
  15.         log.Fatal(err)
  16.     }
  17.     dbList, err := client.DatabaseList(ctx)
  18.     if err != nil {
  19.         log.Fatal(err)
  20.     }
  21.     fmt.Printf("database list: %v", dbList)
  23.     // creating a context to write in the new database
  24.     resp, err := client.UseDatabase(ctx, &schema.Database{
  25.         Databasename: "myimmutabledb",
  26.     })
  27.     if err != nil {
  28.         log.Fatal(err)
  29.     }
  30.     fmt.Printf("auth token: %v", resp.Token)
  32.     md = metadata.Pairs("authorization", resp.Token)
  33.     ctx = metadata.NewOutgoingContext(context.Background(), md)
  34.     // writing in myimmutabledb
  35.     _, err = client.Set(ctx, []byte(`key`), []byte(`val`))
  36.     if err != nil {
  37.         log.Fatal(err)
  38.     }
  1. immuClient.createDatabase("db1");
  2. immuClient.createDatabase("db2");
  4. immuClient.useDatabase("db1");
  5. try {
  6.     immuClient.set("k0", new byte[]{0, 1, 2, 3});
  7. } catch (CorruptedDataException e) {
  8.     // ...
  9. }
  11. List<String> dbs = immuClient.databases();
  12. // We should have three entries: "defaultdb", "db1", and "db2".

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 projectManagement operations - 图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 createDatabaseReq: Parameters.CreateDatabase = {
  15.         databasename: 'myimmutabledb'
  16.     }
  17.     const createDatabaseRes = await cl.createDatabase(createDatabaseReq)
  18.     console.log('success: createDatabase', createDatabaseRes)
  20.     const useDatabaseReq: Parameters.UseDatabase = {
  21.         databasename: 'myimmutabledb'
  22.     }
  23.     const useDatabaseRes = await cl.useDatabase(useDatabaseReq)
  24.     console.log('success: useDatabase', useDatabaseRes)
  26.     await cl.set('key', 'val')
  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 .Net sdk github projectManagement operations - 图5 (opens new window)

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

Index Cleaning

It’s important to keep disk usage under control. CleanIndex it’s a temporary solution to launch an internal clean routine that could free disk space.

immudb uses a btree to index key-value entries. While the key is the same submitted by the client, the value stored in the btree is an offset to the file where the actual value as stored, its size and hash value. The btree is keep in memory as new data is inserted, getting a key or even the historical values of a key can directly be made by using a mutex lock on the btree but scanning by prefix requires the tree to be stored into disk, this is referred as a snapshot. The persistence is implemented in append-only mode, thus whenever a snapshot is created (btree flushed to disk), updated and new nodes are appended to the file, while new or updated nodes may be linked to unmodified nodes (already written into disk) and those unmodified nodes are not rewritten. The snapshot creation does not necessarily take place upon each scan by prefix, it’s possible to reuse an already created one, client can provide his requirements on how new the snapshot should be by providing a transaction ID which at least must be indexed (sinceTx). After some time, several snapshots may be created (specified by flushAfter properties of the btree and the scan requests), the file backing the btree will hold several old snapshots. Thus the clean index process will dump to a different location only the latest snapshot but in this case also writing the unmodified nodes. Once that dump is done, the index folder is replaced by the new one. While the clean process is made, no data is indexed and there will be an extra disk space requirement due to the new dump. Once completed, a considerable disk space will be reduced by removing the previously indexed data (older snapshots). The btree and clean up process is something specific to indexing. And will not lock transaction processing as indexing is asynchronously generated.

  1.     client.CleanIndex(ctx, &emptypb.Empty{})
  1. immuClient.cleanIndex();

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 projectManagement operations - 图7 (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 projectManagement operations - 图8 (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 projectManagement operations - 图9 (opens new window)

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

HealthCheck

HealthCheck return an error if immudb status is not ok.

  1.     err = client.HealthCheck(ctx)
  1. boolean isHealthy = immuClient.healthCheck();

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

  1. import ImmudbClient from 'immudb-node'
  3. const IMMUDB_HOST = '127.0.0.1'
  4. const IMMUDB_PORT = '3322'
  5. const IMMUDB_USER = 'immudb'
  6. const IMMUDB_PWD = 'immudb'
  8. const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
  10. (async () => {
  11.     await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
  13.     await cl.health()
  14. })()

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 projectManagement operations - 图12 (opens new window)

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