canhazdb

canhazdb

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 using http/https using your favourite http client, or you can use the built in client api.

const client = require('canhazdb/client');

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 client = createClient('https://localhost:8063', { tls });

const document = await client.post('tests', { a: 1 });
const changed = await client.put('tests', { id: document.id }, { query: { b: 2 } });
const changedDocument = await client.getOne('tests', { query: { id: document.id } });

// Capture an event based on regex
// client.on('.*:/tests/.*', ...)
// client.on('.*:/tests/uuid-uuid-uuid-uuid', ...)
// client.on('POST:/tests', ...)
// client.on('DELETE:/tests/.*', ...)
// client.on('(PUT|PATCH):/tests/uuid-uuid-uuid-uuid', ...)

client.on('POST:/tests/.*', (path, collectionId, resourceId, pattern) => {
  console.log(path) // === 'POST:/tests/uuid-uuid-uuid-uuid'
  console.log(collectionId) // === 'tests'
  console.log(resourceId) // === 'uuid-uuid-uuid-uuid'
  console.log(pattern) // === 'POST:/tests/.*'
})

console.log( {
  document, /* { a: 1 } */
  changed, /* { changes: 1 } */
  changedDocument, /* { b: 2 } */
})

Server Via the CLI

npm install --global canhazdb

canhazdb --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

canhazdb --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 --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

const fs = require('fs');
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({
    host: 'localhost', port: 7061, queryPort: 8061, dataDirectory: './canhazdata/one', tls
  })
  const node2 = await canhazdb({
    host: 'localhost', port: 7062, queryPort: 8062, dataDirectory: './canhazdata/two', tls
  })

  await node2.join({ host: 'localhost', port: 7061 })

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

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

  console.log(result.data);

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

Endpoints

	Method	Path	Description
1	GET	/:collectionId?fields	List all documents for a collection
2	GET	/:collectionId/:documentId?query&fields&limit&order	Get a document by id
3	POST	/:collectionId	Create a new document
4	PUT	/:collectionId/:documentId	Replace a document by id
5	PUT	/:collectionId/:documentId?query	Replace multiple document matching query
6	PATCH	/:collectionId/:documentId	Partially update a document by id
7	PATCH	/:collectionId/:documentId?query	Partially update multiple document matching query
8	DELETE	/:collectionId/:documentId	Delete a document by id
9	DELETE	/:collectionId/:documentId?query	Delete multiple document matching query
10	POST	/_/locks	Lock a collection/document/field combination
11	DELETE	/_/locks/:lockId	Release a lock

Examples

1. Get item by id

Method	GET
URL	/collectionId
Fields	JSON Array

HTTP Request:

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

Client:

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

2. Get items in a collection

Method	GET
URL	/collectionId
Query	Mongo Query Syntax
Fields	JSON Array
Limit	Number
Order	Direction(fieldName)

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)'
});

3. Create a new document in a collection

Method	POST
URL	/collectionId
Data	JSON

HTTP Request:

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

Client:

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

4. Replace a document by id

Method	PUT
URL	/collectionId/documentId
Data	JSON

HTTP Request:

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

Client:

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

5. Replace multiple documents by query

Method	PUT
URL	/collectionId/documentId
Data	JSON

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'
  }
});

6. Partially update multiple documents by id

Method	PATCH
URL	/collectionId/documentId
Data	JSON

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'
  }
});

7. Partially update multiple documents by query

Method	PATCH
URL	/collectionId/documentId
Data	JSON

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'
  }
});

8. Delete a document by id

Method	DELETE
URL	/collectionId/documentId

HTTP Request:

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

Client:

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

9. Delete multiple documents by query

Method	DELETE
URL	/collectionId/documentId

HTTP Request:

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

Client:

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

10. Lock a collection/document/field combination

Method	POST
URL	/_/locks
Data	JSON Array

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');

11. Release a lock

Method	DELETE
URL	/_/locks/:lockId

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.