Schema in Code

Defining your database schema in code is a powerful way to manage your data structures which gives a lot of control and benefits such as revisions, reviews and reverts via Git as your data structure scales. This page provides an overview of how to define your database schema in code.

Getting Started

If you haven't yet defined your database schema in code in your project, start by creating the file (in your project's root directory) that will contain the model definitions for your project:

mkdir schema
touch schema/index.ts

A model is defined using the model() function provided by the RONIN client under the ronin/schema path. The ronin/schema path also provides all field type primitives, such as string(), number(), or blob().

Here is an example of a basic schema definition:

import { model, string, date } from 'ronin/schema';
 
export const Account = model({
  slug: 'account',
 
  fields: {
    name: string(),
    handle: string(),
    verifiedAt: date()
  }
});

In the example above, we defined a model named Account with three fields: name, handle, and verifiedAt. Each field is defined using a key-value pair where the key is the slug of the field and the value is the type of the field. See all available field types in the Field Types section.

Once you've defined your models locally, you can compare them to the current state of your database like this:

ronin diff

Running the command above will produce a so-called "migration protocol" in the schema directory. This protocol contains all the steps required to update your database to match your local schema definition.

To apply the changes to your database, run the following command:

ronin apply

Afterward, you can start sending queries to your database that make use of the newly added (or updated) models.

In the future, if you'd like to immediately apply your local changes to your database without first reviewing them, run thhis command:

ronin diff --apply

Like this, the generated migration protocol will be applied immediately.

Field Types

The following types can be used to define fields in a schema:

Link Fields

You can define the relationship of a field to another model like so:

import { model, string, date, link } from 'ronin/schema';
 
export const Account = model({
  slug: 'account',
 
  fields: {
    name: string(),
    handle: string(),
    verifiedAt: date()
  }
});
 
export const Member = model({
  slug: 'member',
 
  fields: {
    account: link({
      target: 'account'
    })
  }
});

In the example above, we defined an additional model named Member with a fields named account that references the Account model.

What if I have multiple repositories?

Once you apply your local schema definition to your database, your local schema definition will be available in your types package (i.e. @ronin/YOUR_SPACE_HANDLE) too. See Automatic Types for more information.

The types package is a separate package that you can install in your other repositories to access the same type definitions in those repositories.