stark-db

SQLite-backed, change-tracking database available over HTTP.

Installation

npm i -g stark-db

Basics

Run with:

stark-db

By default, the DB engine is configured to run over SSL. While some self-signed ssl certificates are automatically generated, they are not ever valid so the user must supply their own. Then, the user needs to set the -c flag in order to enable the cookie security. Only then is this system ready for use in production.

There is a Swagger endpoint https://127.0.0.1:5984/api-docs where the user can try out the routes available.

You may want to use BEGIN IMMEDIATE TRANSACTION; if you write to the database concurrently as SQLite will throw busy errors otherwise.

This database tracks changes to all entities in the auto-created column(on all tables) stark_version. There is also an extra table generated with any user-created table called _stark_del_${name}. Deletions are tracked in this auxiliary set of tables. With the help of this change tracking, synchronization mechanisms can be built later. The user has the option of using soft deletion -- marking data as deleted -- or relying on an id column to track such deletions. ROWID would not work in a synchronization scenario. Any modifications made by stark-db to the sqlite database can be seen by running select * from sqlite_master; and the user can edit the triggers/tables. Also, the -f flag prevents all modifications related to change tracking.

It is recommended to invoke the API one query at a time although it is possible to execute multiple statements in a single invocation. Interactive queries are supported due to the stateful nature of the API. A DB connection is marked inactive and is refreshed after 1 hour. A session cookie to the server is marked inactive after 1 day.

CLI

  -a, --address <address>  HTTP address to listen on (default: "127.0.0.1")
  -i, --doc <address>      Address to query by the documentation (default: "https://127.0.0.1")
  -p, --port <port>        HTTP port to listen on (default: "5983")
  -s, --ssl <port>         HTTPS port to listen on (default: "5984")
  -c, --cookie             Secure cookie, served over valid HTTPS only (default: false)
  -d, --data <path>        Path to the data directory (default: "./data")
  -k, --certs <path>       Path to the certs directory (default: "./certs")
  -f, --simple             Do not run change-tracking queries (default: false)
  -h, --help               display help for command

HTTP API

/{DB}/login

POST /{DB}/login

Summary: DB Login

Description: Logs into a database.

Parameters

Body Example

{
  "username": "admin",
  "password": "admin"
}

Responses

/logout

POST /logout

Summary: User logout

Description:

Logs out of a user.

Parameters

Responses

/users

GET /users

Summary: Get users

Description:

Get the users in the system. Regular users can only get their own user. Admins can get all the users.

Parameters

Responses

POST /users

Summary: Add user

Description:

Add a user. Only Admins can do this.

Parameters

Body Example

{
  "username": "admin",
  "password": "admin",
  "salt": ""
}

Responses

PUT /users

Summary:

Set user

Description:

Set a user. Regular users can only set their own user. Admins can set any user.

Parameters

Body Example

{
  "ID": 2,
  "username": "user1",
  "password": "password1",
  "salt": ""
}

Responses

DELETE /users

Summary: Delete user

Description:

Delete a user. Regular users can only delete their own user. Admins can delete any user.

Parameters

Responses

/DBs

GET /DBs

Summary: Get DBs

Description:

Get the DBs in the system. Regular users can only get their own DBs. Admins can get all the DBs.

Parameters

Responses

POST /DBs

Summary: Add DB

Description:

Add a DB. Only Admins can do this.

Parameters

Body Example

{
  "name": "database1",
  "admins": [
    1,
    2
  ],
  "readers": [],
  "writers": []
}

Responses

PUT /DBs

Summary: Set DB

Description:

Set a DB. DB Admins can update their own DBs while Admins can update all DBs.

Body Example

{
  "ID": 2,
  "name": "database1",
  "admins": [
    1,
    2
  ],
  "readers": [],
  "writers": []
}

Parameters

Responses

DELETE /DBs

Summary: Delete DB

Description:

Delete a DB. DB Admins can delete their own DBs while Admins can delete any DB.

Parameters

Responses

/{DB}/query

POST /{DB}/query

Summary: DB Query

Description:

Queries a database.

Parameters

Body Example

{
  "query": "SELECT * FROM sqlite_master;",
  "params": []
}

Responses