Skip to main content

Manage Group

In zkDatabase, managing users within a group or database is an essential part of permission and access control. The methods below help you check group existence, read group info, update group metadata, and add/remove users.

Check Group Exists​

Definition​

await zkdb
  .db(databaseName: string)
  .group(groupName: string)
  .exist(): Promise<boolean>;

Parameters​

  • None

Returns​

  • Promise<boolean>: Returns true if the group exists in the database, false if it doesn't exist. This is useful for conditional group operations, validation checks, and preventing errors when attempting operations on non-existent groups.

Example​

const dbTest = zkdb.db('zkdb_test');
const exist = await dbTest.group('Team').exist();

Group Info​

Definition​

await zkdb
  .db(databaseName: string)
  .group(groupName: string)
  .info(): Promise<TGroupDetail | null>;

Parameters​

  • None

Returns​

  • TGroupDetail | null: Group detail with user list.
type TGroupDetail = {
  groupName: string;
  groupDescription: string;
  createdBy: string;
  createdAt: string | Date;
  updatedAt: string | Date;
  listUser: Array<{
    userName: string;
    createdAt: string | Date;
    updatedAt: string | Date;
  }>;
} | null;

Update Group Metadata​

Definition​

await zkdb
  .db(databaseName: string)
  .group(groupName: string)
  .update({ newGroupName?: string; newGroupDescription?: string }): Promise<boolean>;

Parameters​

  • newGroupName (string, optional)
  • newGroupDescription (string, optional)

Returns​

  • Promise<boolean>: Returns true when the group metadata is successfully updated with the new name and/or description. The changes take effect immediately and are reflected in all group operations and access control.

Add Users to Group (userAdd)​

Definition​

await zkdb
  .db(databaseName: string)
  .group(groupName: string)
  .userAdd(listUser: string[]): Promise<boolean>;

Parameters​

  • listUser (string[]): An array of usernames that you want to add to the database or group. Each username must be a valid, registered user in the system.

Returns​

  • Promise<boolean>: Returns true when all specified users are successfully added to the group. The users immediately gain access to collections and resources associated with this group's permissions.

Example​

const result = await zkdb.db('zkdb_test')
  .group('dev')
  .userAdd(['alice', 'bob']);

// Result:
// true

In this example, the users alice and bob are added to the database group. The method returns true if the operation is successful, or false if it fails.

Remove Users from Group (userRemove)​

Definition​

await zkdb
  .db(databaseName: string)
  .group(groupName: string)
  .userRemove(listUser: string[]): Promise<boolean>;

Parameters​

  • listUser (string[]): An array of usernames that you want to remove from the database or group.

Returns​

  • Promise<boolean>: Returns true when all specified users are successfully removed from the group. The users immediately lose access to collections and resources that were accessible through this group's permissions.

Example​

const result = await zkdb.db('zkdb_test')
  .group('dev')
  .userRemove(['alice', 'bob']);

// Result:
// true

In this example, the users alice, bob are removed from the database group. The method returns true if the operation is successful, or false if it fails.

Important Notes​

  • Permission Requirements: Only the database owner or a user with the appropriate permissions can call userAdd and userRemove to modify user access. Attempting to call these methods without the proper permissions will result in an error.

  • Error Handling: Both methods return a promise that resolves to true or false. It is recommended to handle errors or unsuccessful attempts using .catch() or a try...catch block.

  • Batch Operations: Both userAdd and userRemove work with an array of usernames, allowing you to manage multiple users at once for efficiency.

Use Cases​

  • Group Management: These methods are useful for managing access to specific groups within a database. For example, you can use userAdd to grant a group of employees access to a specific resource or userRemove to revoke access from users who are no longer part of a project.

  • Security and Access Control: By adding and removing users, you can maintain tight control over who can access sensitive data, ensuring that only authorized users have permissions to interact with the database or its contents.