Define a Schema

This guide will walk you though defining a basic StatelyDB Schema. Schema is how you define all the different data models you’ll store in the database - their structure, data types, and key paths. First you’ll get your development environment set up, then you’ll define and publish a schema.

Prerequisites

• Make sure you’ve followed all the steps in Getting Started. You will need to download the StatelyDB CLI, which is needed for working with schema definitions, and you should have a Store and an empty Schema created for you.
• You will need to install NodeJS because our Schema language is based on TypeScript.

Create your schema

Stately schemas are TypeScript code that’s checked in to your code repository alongside your service code. You write your schema in TypeScript even if you’ll be using a Go, Ruby, or Python client. You describe all of your data types in code, and then use the Stately CLI to publish changes to it. Each StatelyDB Store has an associated schema, and multiple stores can share the same schema.

In your code repository, use the StatelyDB CLI to initialize a new schema package (it can be any directory name you want but we’ll call it schema here):

stately schema init ./schema

This will create a directory containing a new NodeJS package:

schema/.gitignore
schema/package.json
schema/README.md
schema/schema.ts
schema/tsconfig.json

Next we’ll need to install the NPM dependencies:

cd ./schema
npm install # or whatever your favorite JavaScript package manager is

The schema.ts file is where you will write your schema, using helper methods imported from the @stately-cloud/schema package. We recommend opening the schema directory in VSCode since it has built-in support for TypeScript.

Add an Item Type

Item Types are the top-level documents in your database - you can have many different item types in a Store, and each item type can be manipulated our Data APIs. Many applications have some sort of “user” model, so let’s start with that:

import {
  itemType,
  string,
  timestampSeconds,
  uint,
  uuid,
} from "@stately-cloud/schema";

// A sort of unrelated type used for some simpler examples.
export const User = itemType("User", {
  keyPath: "/user-:id",
  fields: {
    id: {
      type: uuid,
      initialValue: "uuid",
      fieldNum: 1,
    },
    displayName: {
      type: string,
      fieldNum: 2,
    },
    email: {
      type: string,
      fieldNum: 3,
    },
    lastLoginDate: {
      type: timestampSeconds,
      fieldNum: 4,
    },
    numLogins: {
      type: uint,
      fieldNum: 5,
    },
  },
});

There are a few things going on here:

1. First, we import a bunch of schema helpers from the @stately-cloud/schema package. VSCode can help you automatically add these imports.
2. We declare a new Item Type to describe a User. The item type must be exported from the JavaScript module so it is visible to the schema tools.
3. The User item type has a key path of /user-:id. This is like a “primary key” in other databases - it’s the path you’ll use to access a specific user. An individual User might have a key path like /user-p05olqcFSfC6zOqEojxT9g.
4. Lastly there are the actual fields of the item. Each field has a name, a type, and a unique field number. The field number is used to efficiently store the data without having to store the field name every time.
   • There are a few different data types in use - basic types like string, uint (unsigned integer), and more complex types like uuid and timestampSeconds. These are provided as part of @stately-cloud/schema, but you can also make custom types with the type(...) helper function.
   • The id field has an initialValue—this means that StatelyDB will pick a new UUID whenever you create a new User.

This is just scratching the surface of what you can express with schema. See Defining Item Types for more things to try.

Generating Language-Specific Code

You can now generate typed client code for one of our supported programming languages. This is done via the StatelyDB CLI with the command:

Go

stately schema generate --language go ./schema/schema.ts lib

Ruby

stately schema generate --language ruby ./schema/schema.ts lib

Python

stately schema generate --language python ./schema/schema.ts lib

TypeScript

stately schema generate --language ts ./schema/schema.ts lib

If you look in the lib directory, you’ll now see some files that export a customized client and objects for all of your item types.

Publishing your schema

Once you have written out your schema definition, you need to publish the schema into your Stately Cloud account. First, find the Schema ID of the schema you want to update, then using the StatelyDB CLI:

stately schema put --schema-id <your schema ID> path/to/schema.ts

In order for your Store to use this schema, the schema needs to be “bound” to the store. This only needs to happen once per store, and a single schema can be bound to multiple stores. Using the CLI:

stately schema bind --schema-id <your schema ID> --store-id <your store ID>