LightDB (RFC-023)

The proposal has been accepted and has an implementation.

Document Maintainers: Andi Gabriel Tan 2023. List of other contributors in Annex. 1.

Copyright: MIT license

Copyright © 2018-2023 Axiologic Research and Contributors. This document is licensed under MIT license.


This RFC provides an in-depth examination of LightDB, a generic storage service tailored for ApiHub that aims to enhance the scalability of ApiHub. This RFC elucidates the core idea behind LightDB, emphasizing the importance of stateless ApiHub components and the adoption of LightDB or disk storage, bolstering the flexibility of traffic routing via load balancers. Although LightDB is not intrinsically designed for scalability, it accommodates CRUD operations, thus serving ApiHub components effectively. This RFC also presents the LightDB Endpoints technical description that dives into the technicalities of the LightDB, underpinned by a singular endpoint allowing commands. The embedded database, LokiJS, used by the default implementation, can be substituted, adhering to the standard interface, and rendering the endpoint as a remote function call interface. The RFC also offers insights into the deployment strategies of an external LightDB endpoint. By default, ApiHub comes with an internal LightDB component, but from an environment variable, it is possible to direct ApiHub instances towards an external endpoint. This RFC endeavors to equip developers and architects with comprehensive knowledge of LightDB's integration with OpenDSU and ApiHub.

1. LighDB Concept and Purpose

LightDB serves as a generic storage mechanism for ApiHub components, enabling the scalability of ApiHub. It is recommended that ApiHub components avoid state storage in memory (between calls) and instead utilize LightDB or a disk storage (which can be sourced from a network file system). This configuration facilitates load balancers or load distribution systems to freely direct traffic to any ApiHub instance. While LightDB itself isn't designed to inherently scale, ApiHub components have the option to employ other LightDB implementations that provide scalable operations.

2. LigtDB Client

The LightDB Client is a class equipped with functions that facilitate CRUD operations toward the LightDB server. These operations include createDatabase, insertRecord, updateRecord, deleteRecord, getRecord, addInQueue, getObjectFromQueue and deleteObjectFromQueue.

Function createDatabase(dbName, callback)

Description: Create a database with the name dbName.

Function insertRecord(forDID, table, pk, encryptedRecord, callback)

Description: Insert a record (encryptedRecord) into a database (table).

Function updateRecord(forDID, table, pk, plainRecord, encryptedRecord, callback)

Description: Update a record that already exists in table.

Function deleteRecord(forDID, table, pk, callback)

Description: Delete a record from a database (table).

Function getRecord(forDID, table, pk, callback)

Description: Retrieve a record from table.

Function addInQueue (forDID, queueName, encryptedObject, ensureUniqueness, callback)

Description: Insert a record into the queue.

Function getObjectFromQueue(forDID, queueName, hash, callback)

Description: Retrieve a record from the queue.

Function deleteObjectFromQueue(forDID, queueName, hash, callback)

Description: Delete a record from the queue.

3. LighDB Endpoints

The LightDB enclave is based on a single endpoint that takes CRUD commands for working with records in databases that store records in tables. By default, an embedded database is used (LokiJS), but, following the standard interface, other databases could be used for the actual storage. The endpoint allows a command with a variable number of arguments and, in a way, it could be seen as a remote function call interface.

PUT /createDatabase/:dbName
PUT /executeCommand/:dbName

The first element in params is a DID, used to verify the signature from body.signature. The signature is signing the command object (commandName, params).

4. Deployment configurations

The LIGHT_DB_SERVER_ADDRESS environment variable is used to instruct APIHub instances about the endpoint (specifically instructing the LightDB Client) to which they should connect. By default, the LIGHT_DB_SERVER_ADDRESS is generated by APIHub upon startup (and it starts a LightDB server). If LIGHT_DB_SERVER_ADDRESS is set, then APIHub will not attempt to start a new LightDB Server.


  1. Axiologic Research: New content and improvements. Original texts under PharmaLedger Association and Novartis funding. MIT licensed content accordingly with the contracts. Publish and maintain the site.


Current Editors Email
Andi-Gabriel Țan
Teodor Lupu
Contributors Axiologic Research Email
Sînică Alboaie
Daniel Sava
Cosmin Ursache
Teodor Lupu