Over the Network

Configuring an over-the-network instance and connecting to it

How over-the-network connections work

Running a network-exposed instance

When you install tydb locally (npm i tydb) or globally (npm i -g tydb), you'll get a CLI tool to run a network exposed instance of TyDB.

Before you run the command, you'll have to setup a configuration file, written in typescript, with a name that ends with .tydb.ts like this:

config.tydb.ts

import {
	BaseModel,
	FS_Persistence_Adapter,
	DatabaseConfigurations,
} from "./src";

class MyModel extends BaseModel {
	name: string = "";
	male: boolean = false;

	get female() {
		return !this.male;
	}
}

/**
 * you can define multiple database
 * to be exposed over the network
 */
export const databases: 
	{ [key: string]: DatabaseConfigurations<any> } 
	= {
	// "mydb" will be used as a namespace for
	// the database connection URL
	// (e.g. tydb://http://localhost:3000/mydb)
	mydb: {
		// "workspace/external" is the file
		// path that the database
		// data will be saved to
		ref: "workspace/external",
		// a model that your documents
		// will confirm to
		model: MyModel,
		afterSerialization: (string) => {
			// if you want to do any
			// special encoding/encryption
			return string;
		},
		beforeDeserialization: (string) => {
			// if you want to do any
			// special decoding/decryption
			return string;
		},
		// no tolerance for corruption
		corruptAlertThreshold: 0,
		// add createdAt & updatedAt fields
		timestampData: true,
		// use a persistence adapter
		// (defaults to file system)
		persistence_adapter: FS_Persistence_Adapter,
		// set an interval for auto compaction
		// defaults to 0 = no auto compaction
		autoCompaction: 0,
	},
};

/**
 * fastify server configurations
 */
export const fastify = {
	// listening options
	// more: https://www.fastify.io/docs/latest/Server/#listen
	listen: {
		port: 3000,
		host: "127.0.0.1",
	},
	// server options
	// more: https://www.fastify.io/docs/latest/Server/
	server: {
		logger: false,
	},
	// set this to undefined to disable cors
	// more: https://github.com/fastify/fastify-cors
	cors: {},
};

• Each property in the databases field represents a database, the key of this property (e.g. ns1) is the namespace that you would use to connect to this specific database. The value of this property is the database configuration. Read more about database configuration.

• TyDB uses fastify framework to serve the database over the network. Hence the fastify field contains configurations related to fastify.

  • Read more about listening options.

  • Read more about server options.

  • Read more about CORS options.

Using a node process manager

To run such TyDB in production you may need to have some kind of process manager, this is not included to give you more freedom and choice over which process manager you'd like to have, here's an example of how to do it using PM2 as an example.

After installation of TyDB and PM2 and creating your configs file (e.g. tydb.config.js) run this command:

pm2 start node_modules/.bin/tydb -- tydb.config.js

If you have TyDB globally installed, then run npm root -g to locate the directory in which TyDB is installed. The bin.js file is found in dist directory, so your pm2 command may look like this:

pm2 start ~/.nvm/versions/node/v10.15.0/lib/node_modules/tydb/dist/bin.js -- tydb.config.js

After running the pm2 start command, run the log command

pm2 log

There shouldn't be any errors being logged. And to make sure that your database is being served over the network, head to your browser and type in the host name with the port (e.g. http://localhost:3000), and you should be greeted with a response like this one:

{
    "tydb":"welcome",
    "status":"ok",
    "version":"0.5.3"
}

And when adding the database namespace to the URL (e.g. http://localhost:3000/ns1) and you should see a message like this one:

{
    "tydb":"welcome",
    "dbNamespace":"mydb",
    "databaseFound": true,
    "datafile":"/a/path/to/file",
    "indexesFile":"/a/path/to/file.idx.db"
}

Connecting to the remote instance

Finally, to connect to the database that you've created above, use the connection URL as described in database configuration documentation as the ref.

import { Database, BaseModel} from "tydb";

class MyModel extends BaseModel {
    name: string = "alex";
    yearBorn: number = 1992;
}

const mydb = new Database<MyModel>({
    // notice how the "ref" must
    // start with a "tydb://"
    // and end with the namespace
    // "ns1"
    ref: "tydb://http://localhost:3000/ns1",
    // the same model that you used
    // on the configuration file of the
    // network database should be used
    model: MyModel,
    // all other configuration will be ignored
});