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.
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
Start your first reactive app¶
Next, jump into the directory you just created and start the application:
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:
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:
npx skdbas this keeps the installation of
You can type the same query at the resulting prompt and see that the data is there as well:
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:
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:
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.
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.
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
watchChangesinvokes 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).
Run the service¶
Open a new terminal and run
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.