Database Objects

What if you needed to add a vendor to our database to allow your extension to communicate with a third party?

HQ does not provide an endpoint for all possible operations. For the management of database concepts not covered by HQ, we use a pattern called DB Objects.

DB Objects usually represent a single, abstracted idea, such as a “Logon”, “User”, or “Vendor”. In the database, these likely don’t live all in one place: our schema may require changes to multiple rows in different tables to add, change, or remove individual instances of these concepts.

The intention of DB Objects is to combine these mutually dependant updates into a single operation and free our users from the need to understand exactly how they are represented and configured in the database.

Each DB Object has a consistent interface to perform get, update, and delete operations on its underlying data.

All of the DB Objects are available on the request handler as self.db.

The response will be a list of lxml Objectified Elements, from which you can access information for subsequent use: response[0].DatabaseColumnName.text

Let’s look at how we would add a new vendor to the Q2_Vendor table:

await def add_vendor(self):
    # First let's check to see if our vendor already exists
    already_exists = False
    vendor_to_add = 'VendorOne'

    all_vendors = await self.db.vendor.get()

    # all_vendors is now a list of VendorRows, which each have a known set of properties
    for vendor in all_vendors:
        if vendor.VendorName == vendor_to_add:
            already_exists = True

    # Let's add it if it's not already present
    if not already_exists:
        await self.db.vendor.create(vendor_to_add)

For a full list, refer to DB Objects in the Caliper Class Reference section.

The Vendor should now be correctly configured and present in your database.