Develop with SKDB¶

Develop without a network connection using a local dev-focused SKDB server¶

When developing an application using SKDB, you will likely want to test connecting to the cloud database and replicating data. You can do exactly this of course, but for convenience we also supply a server that is built specifically for development.

The SKDB dev server not only runs locally, enabling you to develop quickly and without a network connection, but also has features specifically to make developing convenient:

Databases are created on demand. Whenever you connect to the dev server supplying a new database name it will spring to life.
You can create users and connect as anyone without needing to manage keys. The keys are exposed on an http endpoint to allow the tooling to work. NEVER run the SKDB dev server in prod.
You do not need to connect and run SQL queries to build and maintain your schema. An http endpoint allows you to PUT the schema that you want. As the schema changes the server will automatically migrate data for you when possible.
- Automatic data migration allows rapidly iterating on your schema during development.
- This feature is exposed programatically by the skdb-dev package.

The SKDB dev server is packaged as a Docker image that you can fetch and run from Docker Hub. Here's how to do so:

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

This will run the server which is accessible on port 3586.

Start building a web app with our quick start project template¶

You can get started quickly with SKDB using our project template hosted on GitHub.

This template provides a pre-configured project using Vite as a bundler. SKDB, React, and TypeScript are setup and ready to be used together.

Either git clone the repo or download and extract the zip to just get the files:

$ wget https://github.com/SkipLabs/skdb_vite_react_starter/archive/refs/heads/main.zip
$ unzip main.zip
$ mv skdb_vite_react_starter-main/ project-name
$ cd project-name/
$ yarn

To start developing:

yarn dev

This will start Vite - the project bundler - and watch the file system for changes. As you edit files and play with SKDB you can see changes reflected instantly in your browser.

When it's time to ship, make sure you've edited package.json to reflect your project name, dependencies, version, etc and then:

yarn build

Start building a node app with our quick start project template¶

You can get started quickly with SKDB using our project template hosted on GitHub.

This template provides a node project pre-configured with SKDB and TypeScript.

Either git clone the repo or download and extract the zip to just get the files:

$ wget https://github.com/SkipLabs/skdb_node_starter/archive/refs/heads/main.zip
$ unzip main.zip
$ mv skdb_node_starter-main/ project-name
$ cd project-name/
$ yarn

To build and run the project:

yarn build && yarn run run

Use the `skdb-dev` package to make development convenient¶

The skdb-dev npm package makes connecting to a local SKDB dev server and getting an SKDB client instance very convenient. It also allows you to specify the remote schema you want to work with and as this changes the dev server will auto migrate your schema and data.

Here's an example, we'll connect to the dev server, specify the schema of the database, get a local database instance, and begin mirroring tables.

import { skdbDevServerDb, createLocalDbConnectedTo } from 'skdb-dev'

async function getStarted(): Promise<SKDB> {
  const remoteDb = await skdbDevServerDb("database-name");

  await remoteDb.schema(
    "CREATE TABLE example_table (id STRING PRIMARY KEY, x STRING, y INTEGER, z FLOAT, skdb_access STRING);",
    "CREATE TABLE another_example (id STRING PRIMARY KEY, x STRING, y INTEGER, z FLOAT, skdb_access STRING);",
  );

  const localDb = await createLocalDbConnectedTo(remoteDb);

  await localDb.mirror(
    {
      table: "example_table",
      expectedColumns: "(id STRING PRIMARY KEY, x STRING, y INTEGER, z FLOAT, skdb_access STRING)"
    }
  );

  // begin populating data and synchronizing it to the server with a local SQL statement
  await localDb.exec("INSERT INTO example_table VALUES (id(), 'foo', 42, 99.9, 'read-write');")

  return localDb;
}

Debug and iterate using the SKDB CLI¶

SKDB comes with a CLI tool which can be used to

query a cloud database
quickly mirror tables and iteratively build and debug queries
inspect schemas
switch to a JavaScript REPL pre-configured with an SKDB database

You can use npx skdb to start the tool.

The CLI will create a local database on each invocation and by default connect to the cloud database. To connect instead to our local dev server, we use the --dev flag.

Let's start a REPL that let's us run queries directly on the remote database (--remote-repl) as the 'root' user (--access-key root):

$ npx skdb --dev --access-key root --db demo --remote-repl
root@ws://localhost:3586/demo> CREATE TABLE test (name TEXT, age INTEGER, skdb_access TEXT);
root@ws://localhost:3586/demo> INSERT INTO test VALUES ('Alice', 42, 'read-write');
root@ws://localhost:3586/demo> SELECT * FROM test;
┌─────────┬─────────┬─────┬──────────────┐
│ (index) │ name    │ age │ skdb_access  │
├─────────┼─────────┼─────┼──────────────┤
│ 0       │ 'Alice' │ 42  │ 'read-write' │
└─────────┴─────────┴─────┴──────────────┘
root@ws://localhost:3586/demo>

The CLI can be instructed using commands that begin with a '.'. Try running .help for a full list.

Let's switch to a local context, mirror our table, insert some data, switch back to the remote context, and check the data replicated successfully:

root@ws://localhost:3586/demo> .local
local> .mirror test
local> INSERT INTO test VALUES ('Bob', 21, 'read-write');
local> .remote
root@ws://localhost:3586/demo> SELECT * FROM test;
┌─────────┬─────────┬─────┬──────────────┐
│ (index) │ name    │ age │ skdb_access  │
├─────────┼─────────┼─────┼──────────────┤
│ 0       │ 'Alice' │ 42  │ 'read-write' │
│ 1       │ 'Bob'   │ 21  │ 'read-write' │
└─────────┴─────────┴─────┴──────────────┘
root@ws://localhost:3586/demo>

Lastly, let's demonstrate the JavaScript REPL. We'll watch a query. If you open a second CLI and modify some mirrored data, you'll see it update in real time.

local> .js
> await skdb.watch("SELECT * FROM test", {}, (rows) => console.log("update:", rows))
update: SKDBTable(2) [
  { name: 'Alice', age: 42, skdb_access: 'read-write' },
  { name: 'Bob', age: 21, skdb_access: 'read-write' },
]
{ close: [Function: close] }
>