Working with KVDBs

KVDBs allow users to access key-value databases. Each Context can contain any number of KVDBs with a unique identifier (kvdbId) used to distinguish them. KVDBs do not need to have unique names or assigned public keys.

Permissions

KVDBs differentiate two types of users - Managers and Regular Users. The table below shows the differences in their permissions:

Activity	User	Manager
Sending entries	yes	yes
Editing KVDB	no	yes
Deleting entries	only their own	all entries

The values above are the default policy values defined by PrivMX. To read more about Policies and learn how to modify them, go to Policies.

Before working with KVDBs, follow our Getting Started Guide. It will show you how to set up your project to work with PrivMX Bridge. Sample code on this page is based on the initial assumptions.

When working with KVDBs, you will use the following:

KvdbApi - provides methods used to manage KVDBs in given Context

Let's modify the project from the First App chapter to connect to PrivMX Bridge, create a KVDB, and set the first entry in it.

CMakeLists.txt

...
target_link_libraries(test_program PUBLIC 
		privmxendpoint::privmxendpointcore
        privmxendpoint::privmxendpointkvdb
		privmxendpoint::crypto
)

main.cpp

C++

// setup some defaults
core::PagingQuery defaultListQuery = {.skip = 0, .limit = 100, .sortOrder = "desc"};

// initialize Endpoint connection and KVDBs API
auto connection {core::Connection::connect(USER1_PRIVATE_KEY, SOLUTION_ID, BRIDGE_URL)};
auto kvdbApi {kvdb::KvdbApi::create(connection)};

// ...

Creating KVDBs

Creating a basic, unnamed KVDB, which can act as an encrypted key-value database:

C++

// ...

std::vector<core::UserWithPubKey> managers {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY}
};

std::vector<core::UserWithPubKey> users {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY},
    {.userId = USER2_ID, .pubKey = USER2_PUBLIC_KEY}
};

// create a new KVDB with access for USER_1 as manager and USER_2 as regular user
auto kvdbId {kvdbApi.createKvdb(
    CONTEXT_ID, 
    users, managers, 
    core::Buffer::from("some kvdb's public meta-data"), 
    core::Buffer::from("some kvdb's private meta-data")
)};

// ...

Hint: You can assign any data to private and public meta fields (e.g. the KVDB's name), as long as it is serialized and can be given as the core::Buffer.

Fetching KVDBs

Getting a list of KVDBs available for the user in the given Context:

C++

// ...

auto kvdbList = kvdbApi.listKvdbs(CONTEXT_ID, defaultListQuery);

// ...

As a result you will receive an object:

C++

// kvdbsList:
{
    readItems: [<kvdbObject1>, <kvdbObject2>,..., <kvdbObjectN>],
    totalAvailable: <number_of_all_kvdb>
}

Getting a Single KVDB:

C++

// ...

auto kvdb = kvdbApi.getKvdb(kvdbId);

// ...

A detailed description of the Kvdb object fields can be found in API Reference.

Modifying KVDBs

To update a KVDB you must always provide a full list of parameters.

The updateKvdb(...) method needs all the parameters as in the createKvdb(...) method and a few more. If you want to update one of the parameters – provide it in a new modified form. If, on the other hand, you want to leave the parameter unchanged – provide it as it was before.

C++

// ...
auto currentKvdb {kvdbApi.getKvdb(kvdbId, defaultListQuery)};

std::vector<core::UserWithPubKey> managers {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY}
};

std::vector<core::UserWithPubKey> users {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY}
};

// update a new KVDB with access for USER_1 as the only user.
kvdbApi.updateKvdb(
    kvdbId, 
    users, managers, 
    currentKvdb.publicMeta, 
    currentKvdb.privateMeta,
    currentKvdb.version, // <- pass the version of the KVDB you will perform the update on
    false, // <- force update (without checking version)
    false // <- force to regenerate a key for the KVDB
);

// ...

Deleting KVDBs

To delete a KVDB, you need to use the deleteKvdb(...) method.

C++

// ...
kvdbApi.deleteKvdb(kvdbId);
// ...

Working with KVDBs

Permissions