feathers-harperdb
This library is a FeathersJS database adapter for HarperDB - an LMDB/NodeJS-based, high-scale, database. It uses a combination of the raw HarperDB RESTful endpoints and KnexJS-translated queries through HarperDB's subset of supported SQL commands. It also uses Harperive for authentication, promise management, and connectivity.
npm install --save feathers-harperdb
Important:
feathers-harperdb
implements the Feathers Common database adapter API and querying syntax.
API
service(options)
const service = require('feathers-harperdb');
app.use('/messages', service({
//...options
}););
Options:
-
name
(required) - The name of the table -
config
(required) - Usually set inconfig/{ENV}.json
. See "Connection Options" below -
client
(optional) - The Harperive Client, can be manually overriden and accessed -
id
(optional, default:id
) - The name of the id field property. -
events
(optional) - A list of custom service events sent by this service -
paginate
(optional) - A pagination object containing adefault
andmax
page size -
multi
(optional) - Allowcreate
with arrays andupdate
andremove
withid
null
to change multiple items. Can betrue
for all methods or an array of allowed methods (e.g.[ 'remove', 'create' ]
) -
whitelist
(optional) - A list of additional query parameters to allow (e..g[ '$regex', '$geoNear' ]
). Default is the supportedoperators
-
sortField
(optional, default:__createdtime__
) - By default all objects will be sorted ASC by created timestamp, similar to sorting by Integer auto-incrementedid
in most feather SQL operations -
sortDirection
(optional, default:asc
) - The default sort direction, can be one of[ 'asc', 'desc' ]
-
limit
(optional, default:5000
) - The max number of objects to return without pagination, will be overriden by pagination settings -
sync
(optional, default:true
) - Setting true will create schema and table on load as part of theservice.setup()
function run by FeathersJS -
force
(optional, default:false
) , Settign true will delete the schema on setup, starting with fresh database with every boot, much like Sequelize'sforceSync
.
Connection Options:
The connection options are passed in as a config
object inside the options object (i.e. harper({ config: { ...connection_options } })
)
-
schema
(required) - The name of the schema (i.e. DB-equivalent) in the HarperDB instance -
harperHost
(required) - The location of the Harper Host -
username
(required) - The username to connect with -
password
(required) - The password to connect with -
table
(optional) - The name of the table referenced by the service, defaults toname
, but can be overriden by settingconfig.table
These can also be set via a "harperdb" configuration field in the Feathers config/{ENV}.json
:
"harperdb":{
"harperHost": "http://localhost:9925",
"username": "admin",
"password": "password",
"schema": "test"
}
Setting up Service
To set up your service, your service class.js and service.js files should look something like this:
//books.class.js
const { Service } = require('feathers-harperdb');
exports.Books = class Books extends Service{
constructor(options, app) {
super({
...options,
name: 'books'
});
}
};
//books.service.js
const { Books } = require('./books.class');
const hooks = require('./books.hooks');
module.exports = function (app) {
const options = {
paginate: app.get('paginate'),
config: {
...app.get('harperdb'),
table: 'books'
}
};
app.use('/books', new Books(options, app));
const service = app.service('books');
service.hooks(hooks);
};
Querying
In addition to the common querying mechanism, this adapter also supports direct NoSQL submissions via the Harperive client like this:
let service = app.service('books')
await service.client.insert({
table: this.table,
records: [
{
user_id: 43,
username: 'simon_j',
first_name: 'James',
middle_name: 'J.',
last_name: 'Simon'
}
]
})
.then((res) => console.log(res))
.catch((err) => console.log(err));
You can also use Harperive's generic execution option like so:
const options = {
operation: 'harperdb_operation',
//other fields...
};
// Promise
let service = app.service('books')
await service.client.executeOperation(options)
.then((res) => console.log(res))
.catch((err) => console.log(err));