SWARMDB JavaScript API

This is a client library for the SWARMDB API, implemented in JavaScript. It's available on npm as a node module.

To use swarmdb.js, you MUST install our SWARMDB Docker image and set up the SWARMDB node first. Instructions can be found HERE.

Please note that the library is still under heavy development and it might not be stable.

Install

> npm install swarmdb.js

## Configure
Upon installation and startup of your SWARMDB node, a default user and associated private key are generated and stored in the [SWARMDB configuration file](https://github.com/wolkdb/swarm.wolk.com/wiki/9.-SWARMDB-Server-Configuration,--Authentication-and-Voting#configuration-file). 

Set the private key as an environment variable.
This private key is associated with the user configured on the SWARMDB node.
```bash
> export PRIVATE_KEY=PRIVATE_KEY_IN_YOUR_CONFIG_FILE

Import module

var swarmdbAPI = require("swarmdb.js");

Open connection

Open a connection by specifying configuration options like host and port

swarmdbAPI.createConnection(options)

var swarmdb = swarmdbAPI.createConnection({
    host: SWARMDB_HOST, //e.g. "localhost"
    port: SWARMDB_PORT  //e.g. 2001
});

Create database

Create a database by specifying owner, database name and encrypted status.

Owner should be a valid ENS domain.
For encrypted status, 1 means true and 0 means false.

swarmdb.createDatabase(owner, databaseName, encrypted, callback)

swarmdb.createDatabase("test.eth", "testdb", 1, function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Open database

Open a database by specifying owner and database name.

swarmdb.openDatabase(owner, databaseName)

swarmdb.openDatabase("test.eth", "testdb");

List databases

List existing databases.

swarmdb.listDatabases(callback)

swarmdb.listDatabases(function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Drop database

Drop a database by specifying owner and database name.

swarmdb.dropDatabase(owner, databaseName, callback)

swarmdb.dropDatabase("test.eth", "testdb", function (err, result) {
    if (err) {
        throw err;
    }
    console.log(result);
});

Create table

Create a table by specifying table name and column details.

Columns consist of the following parameters:

• indextype: enter the desired indextype, defined HERE
• columnname: enter the desired column name (no spaces allowed)
• columntype: enter the desired columntype, defined HERE
• primary: enter 1 if the column is the primary key and 0 for any other column.

swarmdb.createTable(tableName, columns, callback)

var columns = [
    { "indextype": "BPLUS", "columnname": "email", "columntype": "STRING",  "primary": 1 },
    { "indextype": "HASH",  "columnname": "name",  "columntype": "STRING",  "primary": 0 },
    { "indextype": "BPLUS", "columnname": "age",   "columntype": "INTEGER", "primary": 0 }
];
swarmdb.createTable("contacts", columns, function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Open table

Open a table by specifying table name.

swarmdb.openTable(tableName)

swarmdb.openTable("contacts");

Describe table

Describe a table by specifying table name.

swarmdb.describeTable(tableName, callback)

swarmdb.describeTable("contacts", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Drop table

Drop a table by specifying table name.

swarmdb.dropTable(tableName, callback)

swarmdb.dropTable("contacts", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

List tables

List existing tables.

swarmdb.listTables(callback)

swarmdb.listTables(function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Read / Get / Select

Read a row (or rows) may be done via a Get call or a SQL Select query.

Get

Get calls allow for the retrieval of a single row by specifying the value of a row's primary key.

swarmdb.get(key, callback)

swarmdb.get("[email protected]", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Select

Select Query calls allow for the retrieval of rows by specifying a SELECT query using standard SQL. The supported query operands are allowed to be used on both primary and secondary keys.

swarmdb.query(sqlQuery, callback)

swarmdb.query("SELECT email, name, age FROM contacts WHERE email = '[email protected]'", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

swarmdb.query("SELECT email, name, age FROM contacts WHERE age >= 5", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Write / Put / Insert / Update

Writing a row (or rows) may be done via a Put call or a SQL Insert query.

Put

Put calls allow for writing rows.

Note: The "rows" input consists of an array of rows, where a row is a defined as a JSON object containing column/value pairs. Each row must at least include a column/value pair for the primary key.

swarmdb.put(rows, callback)

swarmdb.put( [ { "email": "[email protected]", "name": "Bertie Basset", "age": 7 }, { "email": "[email protected]", "name": "Paul", "age": 25 } ],  function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Insert

Insert Query calls allow for the insertion of rows by specifying an INSERT query using standard SQL. SWARMDB currently only supports one row insert per call.

swarmdb.query(sqlQuery, callback)

swarmdb.query("INSERT INTO contacts (email, name, age) VALUES ('[email protected]', 'Bertie Basset', 7);", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Update

Update Query calls allow for the update on non-primary key using standard SQL.

swarmdb.query(sqlQuery, callback)

swarmdb.query("UPDATE contacts SET age=8 WHERE email='[email protected]';", function (err, result) {
    if (err) {
      throw err;
    }
    console.log(result);
});

Try out the example

Find the script inside example folder and run it in your Node.js project folder.

> npm install swarmdb.js
> node apitest.js

Run tests for developement

Make sure the private key is configured before running the tests

> git clone https://github.com/wolkdb/swarmdb.js.git
> cd swarmdb.js && npm install
> npm test

Feedback / Question

Email us at [email protected]