Quick-Start Guide

This guide will show you how to set up your SKDB stack and run a web application and service against a local SKDB development server.

You will need to have Docker, Node.js, and Yarn installed.

Get started

Start the server

For your convenience, SkipLabs provides a Docker image via Docker Hub that you can use to run a local SKDB server. Run the following command in a separate terminal window, and you will have a server running at localhost:3586.

docker run -it -p 3586:3586 skiplabs/skdb-dev-server:quickstart

Start your first reactive app

First, we'll clone the example todo-app repo, which contains a simple to-do app built using React and SKDB.

git clone https://github.com/SkipLabs/todo-app.git

Next, jump into the directory you just created and start the application:

cd todo-app && yarn install && yarn dev

See the synchronization in action

You can now open the to-do app by going to localhost:5173. Have a little play! "Tasks" are strings, and you can filter tasks matching a given substring.

When you add a new task, it is automatically synced between the client-side embedded SKDB running in your browser and the server running in Docker.

You can see that the data is available locally by opening the developer console in your browser and executing the following command:

await skdb.exec('SELECT * FROM tasks');

You can also see that the data is synced to the server by opening a SQL REPL from a terminal and pointing it at the server:

cd todo-app && npx skdb --dev --db todo-app --remote-repl

Note: we cd todo-app before npx skdb as this keeps the installation of skdb local to todo-app.

You can type the same query at the resulting prompt and see that the data is there as well:

SELECT * FROM tasks

Real-time collaboration and interaction

Finally, open the to-do app in a second browser tab, as if you were on another device, and add a task there. You can see that everything is kept in sync in real time across all your tabs, and on the server, by: deleting or adding tasks; or running queries in the REPL or either client.

Set up a reactive service

Suppose that you want to log changes to your to-do list to another file or database. It's easy to build a Node service to do that with SKDB: todo-app contains an example in services/src/skdb-log.ts, which we'll walk you through now.

Connect to the database

The first thing that the service does is connect to the remote server and specify the schema:

const remoteDb = await skdbDevServerDb("todo-app", "localhost", 3586);
await remoteDb.schema(
  "CREATE TABLE tasks (id TEXT PRIMARY KEY, name TEXT, complete INTEGER, skdb_access TEXT);",
);

Next, it creates a local SKDB instance connected to the remote and mirroring its tasks table. You can also specify a filter to mirror only a subset of the data locally, but we'll mirror the full table here.

const localDb = await createLocalDbConnectedTo(remoteDb, "root");
await localDb.mirror({
  table: "tasks",
  expectedColumns:
    "(id TEXT PRIMARY KEY, name TEXT, complete INTEGER, skdb_access TEXT)",
});

Watch for changes

With that setup, the service's local SKDB is now mirroring the state of the remote database, allowing it to react to any changes made by clients of the to-do app.

Suppose that we are interested in tracking uncompleted tasks only. First, we will create a reactive view of uncompleted tasks, which will be kept up-to-date by the database.

await localDb.exec(
  `CREATE REACTIVE VIEW uncompleted_tasks AS
     SELECT * FROM tasks WHERE complete = 0;`,
);

This reactive view is on the client -- we will later see how to use reactive views on the server as well.

Now, we can watch for changes to uncompleted_tasks -- in this case, we just print the changes to stdout, but you can of course do whatever you want with the data: write it to another database, pass it to another service, etc.

Given an arbitrary query, the function watchChanges invokes a callback on the list of rows that were added and/or removed whenever the results of that query change. Since SKDB uses an incremental engine, those changes can be computed efficiently (without re-running the full query).

await localDb.watchChanges(
  "SELECT * FROM uncompleted_tasks",
  {},
  (initial_rows) => {
    /* ignore */
  },
  (added, removed) => {
    for (let row of added) {
      console.log("ADDED: " + JSON.stringify(row));
    }
    for (let row of removed) {
      console.log("REMOVED: " + JSON.stringify(row));
    }
  },
);

Run the service

Open a new terminal and run

cd todo-app/services && yarn install && npm run skdb-log

Try adding and removing tasks on the to-do app and you will see the service logging updates in real time -- congrats, you just ran an end-to-end reactive system with SKDB!

To see more of what SKDB can do, see the React.js tutorial for a walk-through of adding some interactive features to this demo to-do app.