This repository specifies the interface required to build a database connector for DADI API.
Data connectors must export a constructor function at the root level. The constructor receives an optional object with config parameter overrides, and it should have the following methods in its prototype chain.
const MyDataConnector = function (options) {
this.config = Object.assign({}, config, options)
}
MyDataConnector.prototype.connect = function ({database, collection}) {
// ...
}
module.exports = MyDataConnector
Establishes a connection to the database. API calls it both when establishing a connection for the first time and also when attempting a reconnection.
Parameters:
database
{String}: the name of the database file to usecollection
{Object}: the name of the collection to use
Return value:
Promise
resolved withundefined
if the connection is successfulPromise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection could not be established
Events emitted:
DB_CONNECTED
: when the database connection is establishedDB_ERROR
: when the database connection is closed or times out; an optional error object can be sent as a parameterDB_RECONNECTED
: when the database connection is re-established
Finds documents in a collection.
Parameters:
query
{Object}: the query to performcollection
{String}: the name of the collection to queryoptions
{QueryOptions}: a set of query options, such as offset, limit, sort, fieldsschema
{Object}: the JSON schema for the collectionsettings
{Object}: the settings block of the collection schema
Return value:
Promise
resolved with an object containing:results
: An array with the matching documentsmetadata
: A metadata object, with the format used by @dadi/metadata
Promise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Creates documents in a collection.
Parameters:
data
{Object}: a single document or an Array of documents to insertcollection
{String}: the name of the collection to queryschema
{Object}: the JSON schema for the collectionsettings
{Object}: the settings block of the collection schema
Return value:
Promise
resolved with an object containing an array with the inserted documentsPromise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Updates documents in a collection.
Parameters:
query
{Object}: the query that selects documents for updatecollection
{String}: the name of the collection to updateupdate
{Object}: the update for the documents matching the queryoptions
{QueryOptions}: a set of query options, such as offset, limit, sort, fieldsschema
{Object}: the JSON schema for the collection
Return value:
Promise
resolved with an object containing amatchedCount
property, with a count of the number of documents affected by the update operationPromise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Deletes documents from a collection.
Parameters:
query
{Object}: the query that selects documents for deletioncollection
{String}: the name of the collection to delete fromschema
{Object}: the JSON schema for the collection
Return value:
Promise
resolved with an object containing adeletedCount
property, with a count of the number of documents affected by the delete operationPromise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Gets statistics about the collection.
Parameters:
collection
{String}: the name of the collection to get stats foroptions
{QueryOptions}: a set of query options, such as offset, limit, sort, fields
Return value:
Promise
resolved with an object containing the following properties:count
size
averageObjectSize
storageSize
indexes
totalIndexSize
indexSizes
Promise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Creates indexes in the collection.
Parameters:
collection
{String}: the name of the collection to add indexes toindexes
{Object}: an array of indexes to create for the collection
Return value:
Promise
resolved with an an array of objects representing the indexes, with the name of the collection and the name of the index in thecollection
andindex
properties respectivelyPromise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Retrieves indexes from a collection.
Parameters:
collection
{String}: the name of the collection to get indexes for
Return value:
Promise
resolved with an an array of objects representing the indexes, each with the name of the index in anname
propertyPromise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
Removes a collection from a database or drops the database completely.
Parameters:
collection
{String}: the name of the collection to drop from the database. Usenull
to drop the database.
Return value:
Promise
resolved withundefined
Promise
rejected with anError
object, with a message ofDB_DISCONNECTED
, if the connection to the database is unavailable
DADI API uses one primary configuration file to modify the behaviour of certain functions. In addition to the primary configuration file it also needs a configuration file for the data connector that is being used.
The configuration files for your API Connector must be placed in the same directory as the primary API configuration file, which is commonly config/
.
The naming convention for API Connector configuration files follows the format nameOfConnector.<environment>.json
For example:
- nameOfConnector.development.json
- nameOfConnector.test.json
- nameOfConnector.production.json
The configuration file should contain an configurable properties that a user needs to connect to and configure the underlying data store.
For example:
{
"database": {
"host": "127.0.0.1",
"port": 2101,
"autosaveInterval": 1000
}
}
DADI is a data centric development and delivery stack, built specifically in support of the principles of API first and COPE.
Copyright notice
(C) 2017 DADI+ Limited [email protected]
All rights reserved
This product is part of DADI.
DADI is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version ("the GPL").
If you wish to use DADI outside the scope of the GPL, please contact us at [email protected] for details of alternative licence arrangements.
This product may be distributed alongside other components available under different licences (which may not be GPL). See those components themselves, or the documentation accompanying them, to determine what licences are applicable.
DADI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
The GNU General Public License (GPL) is available at
http://www.gnu.org/licenses/gpl-3.0.en.html.
A copy can be found in the file GPL.md distributed with
these files.
This copyright notice MUST APPEAR in all copies of the product!