Hitchy Odem Manual

Appearance

Adapters ​

Models are relying on adapters for accessing its data in a connected data storage. When defining a model an adapter may be provided to use for all instances of resulting model instead of some default adapter.

This document is about those adapters, how to use them and how to create one yourself.

Available adapters ​

There are two adapters distributed as part of @hitchy/plugin-odem and exposed as service components:

In addition, separate plugins are capable of providing additional adapters, just like:

Adapters expose an API very similar to commonly available key-value stores such as Redis, Etcd and similar making it rather easy to use those instead of a local filesystem for persistently storing managed data.

Storing data in volatile memory ​

The service component OdemAdapterMemory of Hitchy's document-oriented database is an adapter most useful for developing and testing applications as it doesn't actually save any data but manages records in volatile memory, only.

Creating instances doesn't take any options. Different instances manage different sets of records, so it's even possible to have different sets of data separately managed in volatile memory.

javascript
const adapter = new api.services.OdemAdapterMemory();

This adapter may be provided on calling Model.define() explicitly. In a default setup it is also used whenever omitting provision of adapter on calling that function.

Storing data in local filesystem ​

This adapter is meant to implement a very basic opportunity to persistently save records without relying on any additional software. It is thus suitable for smaller, single-node applications e.g. desktop software based on Electron.

When using it all records are saved in a folder of your local filesystem. That's why you should provide the path name of folder to contain all those files as option on creating instances of OdemAdapterFile:

javascript
const adapter = new api.services.OdemAdapterFile( {
   dataSource: "/path/name/of/a/folder"
} );

Storing data in etcd cluster ​

Separate plugin @hitchy/plugin-odem-etcd enables data being persisted in an etcd cluster, too. This option is intended for use with production setups running in a cluster enabling horizontal scaling of your Hitchy application.

See the plugin's documentation for up-to-date information on how to integrate it with your application. The following excerpt is meant to demonstrate the ease of integrating Odem with etcd cluster instead of some local filesystem, only:

javascript
const adapter = new api.services.OdemAdapterEtcd( {
    hosts: [
        "https://etcd1:2379",
        "https://etcd2:2379",
        "https://etcd3:2379",
    ],
    // optional: share single etcd cluster with multiple apps
    prefix: "/apps/my-app",
    auth: {
        username: "etcd-login-user",
        password: "secret-pw",
    },
    // optional: authenticate server and client on encrypted connections
    credentials: {
        rootCertificate: require( "fs" ).readFileSync( "path/to/ca.pem" ),
        certChain: require( "fs" ).readFileSync( "path/to/cert.pem" ),
        privateKey: require( "fs" ).readFileSync( "path/to/key.pem" ),
    }
} );

Configuring default adapter ​

In compliance with Hitchy's conventions you may create a file config/database.js in your Hitchy-based project's folder with content like this:

javascript
const File = require( "fs" );

module.exports = function() {
    return {
        database: {
            default : new this.runtime.services.OdemAdapterFile( {
                dataSource: "/path/name/of/a/folder"
            } ),
        },
    };
};

This example is replacing the default adapter storing all data in volatile memory with another adapter storing all data in a folder of your local filesystem.