canhazdb-server

A sharded and clustered database communicated over http rest with notifications included.

Getting Started

You must have a minimum version of Node 12 installed.

Create the tls files you need to secure your cluster.

A bash script ./makeCerts.sh provided will create a folder with test certs you can use.

You can opt out of tls by omitting the tls option from canhazdb.

Client

You can talk to the database via http/https using your favourite http client, or you can use the official client.

Drivers

As of version 5.0.0, drivers have been abstracted out and installed separately.

The current official drivers are:

• canhazdb-driver-ejdb
• canhazdb-driver-nedb
• canhazdb-driver-sqlite

It should be fairly trivial to implement a driver for other databases. If you would like to create a custom driver, take a look at the nedb driver index file for an example.

Server Via Docker

The quickest way to setup a test server is via:

docker run -itp 8060:8060 canhazdb/server --single

Then visit http://localhost:8060

But you can create a production ready and scalable stack by using the stack.yml file as an example.

This will give you TLS authenication and encryption along with persistent storage.

Server Via the CLI

npm install --global canhazdb-server

Create a single node server

canhazdb-server \
         --driver canhazdb-driver-ejdb \
         --host localhost \
         --port 7061 \
         --query-port 8061 \
         --data-dir ./canhazdb/one \
         --tls-ca ./certs/ca.cert.pem \
         --tls-cert ./certs/localhost.cert.pem \
         --tls-key ./certs/localhost.privkey.pem

Add some more to the cluster

canhazdb-server \
         --driver canhazdb-driver-ejdb \
         --host localhost \
         --port 7062 \
         --query-port 8062 \
         --data-dir ./canhazdb/two \
         --tls-ca ./certs/ca.cert.pem \
         --tls-cert ./certs/localhost.cert.pem \
         --tls-key ./certs/localhost.privkey.pem \
         --join localhost:7061

canhazdb-server \
         --driver canhazdb-driver-ejdb \
         --host localhost \
         --port 7063 \
         --query-port 8063 \
         --data-dir ./canhazdb/three \
         --tls-ca ./certs/ca.cert.pem \
         --tls-cert ./certs/localhost.cert.pem \
         --tls-key ./certs/localhost.privkey.pem \
         --join localhost:7061

Server Via NodeJS

npm install --save canhazdb-server canhazdb-driver-ejdb

const fs = require('fs');
const https = require('https');
const axios = require('axios');
const canhazdb = require('canhazdb-server');

async function main () {
  const tls = {
    key: fs.readFileSync('./certs/localhost.privkey.pem'),
    cert: fs.readFileSync('./certs/localhost.cert.pem'),
    ca: [ fs.readFileSync('./certs/ca.cert.pem') ],
    requestCert: true /* this denys any cert not signed with our ca above */
  };

  const node1 = await canhazdb({
    driver: 'canhazdb-driver-ejdb',
    host: 'localhost',
    port: 7061, queryPort: 8061,
    dataDirectory: './canhazdata/one',
    tls, single: true
  });
  const node2 = await canhazdb({
    driver: 'canhazdb-driver-ejdb',
    host: 'localhost',
    port: 7062, queryPort: 8062,
    dataDirectory: './canhazdata/two',
    tls, join: ['localhost:7061']
  });

  // You can join to other nodes after starting:
  // await node2.join({ host: 'otherhost', port: 7063 })

  const postRequest = await axios(`${node1.url}/tests`, {
    httpsAgent: new https.Agent(tls),
    method: 'POST',
    data: {
      a: 1,
      b: 2,
      c: 3
    }
  });

  // node2.url === 'https://localhost:8061'
  const result = await axios(`${node2.url}/tests/${postRequest.data.id}`, {
    httpsAgent: new https.Agent(tls)
  });

  console.log(result.data);

  /*
    {
      a: 1,
      b: 2,
      c: 3
    }
  */
}

System Tables

The system namespace is used for storing the following metadata related to the database.

You can query them like any normal collection.

collections

The system.collections collection contains a document for each collection, along with the amount of documents that stores.

axios('/system.collections', {
  httpsAgent: new https.Agent(tls)
}) === [{
 id: 'uuid-uuid-uuid-uuid',
 collectionId: 'tests',
 documentCount: 1
}]

Endpoints

Examples

HTTP Request:

axios({
  url: 'https://localhost:8061/tests/example-uuid-paramater?fields=["firstName"]',
})

Client:

client.get('tests', { 
  query: {
    id: 'example-uuid-paramater'
  }
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests?count=true&query={"firstName":"Joe"}',
})

Client:

client.count('tests', {
  query: {
    firstName: 'Joe'
  }
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests?query={"firstName":"Joe"}&fields=["firstName"]&limit=10&order=desc(firstName)',
})

Client:

client.get('tests', {
  query: {
    firstName: 'Joe'
  },
  limit: 10,
  order: 'desc(firstName)'
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests',
  method: 'POST',
  data: {
    firstName: 'Joe'
  }
})

Client:

client.post('tests', {
  firstName: 'Joe'
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests/example-uuid-paramater',
  method: 'PUT',
  data: {
    firstName: 'Zoe'
  }
})

Client:

client.put('tests', {
  firstName: 'Joe'
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests?query={"location":"GB"}',
  method: 'PUT',
  data: {
    firstName: 'Zoe',
    location: 'GB',
    timezone: 'GMT'
  }
})

Client:

client.put('tests', {
    firstName: 'Zoe',
    location: 'GB',
    timezone: 'GMT'
}, {
  query: {
    location: 'GB'
  }
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests/example-uuid-paramater',
  method: 'PATCH',
  data: {
    timezone: 'GMT'
  }
})

Client:

client.patch('tests', {
    timezone: 'GMT'
}, {
  query: {
    location: 'GB'
  }
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests?query={"location":"GB"}',
  method: 'PATCH',
  data: {
    timezone: 'GMT'
  }
})

Client:

client.patch('tests', {
    timezone: 'GMT'
}, {
  query: {
    location: 'GB'
  }
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests/example-uuid-paramater',
  method: 'DELETE'
})

Client:

client.delete('tests', {
  query: {
    id: 'example-uuid-paramater'
  }
});

HTTP Request:

axios({
  url: 'https://localhost:8061/tests?query={"location":"GB"}',
  method: 'DELETE'
})

Client:

client.delete('tests', {
  query: {
    location: 'GB'
  }
});

HTTP Request:

const lock = await axios({
  url: 'https://localhost:8061/_/locks',
  method: 'POST',
  data: ['users']
});
const lockId = lock.data.id;

Client:

const lockId = await client.lock('users');

HTTP Request:

const lock = await axios({
  url: 'https://localhost:8061/_/locks',
  method: 'POST',
  data: ['users']
});
const lockId = lock.data.id;

const lock = await axios({
  url: 'https://localhost:8061/users',
  method: 'POST',
  headers: {
    'x-lock-id': lockId,
    'x-lock-strategy': 'wait' // optional: can be 'fail' or 'wait'. default is 'wait'.
  }
});

await axios({
  url: `https://localhost:8061/_/locks/${lockId}`,
  method: 'DELETE'
});

Client:

const lockId = await client.lock(['users']);
const newDocument = await client.post('users', {
  name: 'mark'
}, {
  lockId,
  lockStrategy: 'wait' // optional: can be 'fail' or 'wait'. default is 'wait'.
});
await client.unlock(lockId);

License

This project is licensed under the terms of the AGPL-3.0 license.