Tailor DB

The primary database within Tailor Platform, where you store and retrieve your data, is known as Tailor DB. Tailor DB provides a flexible and scalable database that you build using schema. A GraphQL endpoint is automatically generated, enabling seamless fetching, creation, updating, and deletion of records. Additionally, it allows for easy sorting and filtering by any field.

Defining a schema

A data model of your application is defined by the schema. Although multiple data models can be defined in one single schema file, we recommend using one or a few data models per one schema file for readability.

To define the schema, we recommend using the CUE language. All of our templates are also defined in CUE. With a single line of command, the Tailor platform will then generate the GraphQL SDL (Schema Definition Language) based on the .cue schema provided, which in turn will be used to generate the GraphQL API. From now on in this document, a "schema" refers to the schema file defined in CUE.

Folder structure overview

Below is the folder structure of Inventory Management System app example in the tutorial.

<span><span style="color: var(--shiki-color-text)">ims </span><span style="color: var(--shiki-token-comment)">// Root folder for an app</span></span>
<span><span style="color: var(--shiki-color-text)">├── </span><span style="color: var(--shiki-token-constant)">cue</span><span style="color: var(--shiki-color-text)">.mod </span><span style="color: var(--shiki-token-comment)">// Points to the Tailor Platform configuration files</span></span>
<span><span style="color: var(--shiki-color-text)">├── </span><span style="color: var(--shiki-token-constant)">workspace</span><span style="color: var(--shiki-color-text)">.cue</span></span>
<span><span style="color: var(--shiki-color-text)">├── application</span></span>
<span><span style="color: var(--shiki-color-text)">│       └── </span><span style="color: var(--shiki-token-constant)">app</span><span style="color: var(--shiki-color-text)">.cue</span></span>
<span><span style="color: var(--shiki-color-text)">├── services</span></span>
<span><span style="color: var(--shiki-color-text)">│       └── auth</span></span>
<span><span style="color: var(--shiki-color-text)">│           └── </span><span style="color: var(--shiki-token-constant)">auth</span><span style="color: var(--shiki-color-text)">.cue</span></span>
<span><span style="color: var(--shiki-color-text)">│       └── pipeline</span></span>
<span><span style="color: var(--shiki-color-text)">│           └── </span><span style="color: var(--shiki-token-constant)">pipeline</span><span style="color: var(--shiki-color-text)">.cue</span></span>
<span><span style="color: var(--shiki-color-text)">│       └── tailordb </span></span>
<span><span style="color: var(--shiki-color-text)">│           └── </span><span style="color: var(--shiki-token-constant)">tailordb</span><span style="color: var(--shiki-color-text)">.cue  </span><span style="color: var(--shiki-token-comment)">// The root schema of the Tailor DB</span></span>
<span><span style="color: var(--shiki-color-text)">├── environment </span></span>
<span><span style="color: var(--shiki-color-text)">│       └── </span><span style="color: var(--shiki-token-constant)">env</span><span style="color: var(--shiki-color-text)">.cue</span></span>
<span></span>

We will explain the following files in the document below.

tailordb.cue : the Tailor DB root schema
tailordb/product.cue : defines the model "Product"

Root Tailor DB schema (`tailordb.cue`)

tailordb.cue (required) is a special CUE file that loads all other data models ("types" in GraphQL terminology).

Here is how tailordb.cue looks like.

<span><span style="color: var(--shiki-token-keyword)">package</span><span style="color: var(--shiki-color-text)"> tailordb</span></span>
<span></span>
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> (</span></span>
<span><span style="color: var(--shiki-color-text)">	</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">github.com/tailor-platform/tailorctl/schema/v2/tailordb</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">	</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">tailor.build/template/environment</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">	</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">tailor.build/template/services/tailordb/master</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">)</span></span>
<span><span style="color: var(--shiki-color-text)">tailordb.#Spec </span><span style="color: var(--shiki-token-keyword)">&amp;</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">	Namespace: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">my-tailordb</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">	Types: [</span></span>
<span><span style="color: var(--shiki-color-text)">		{master.Product}</span><span style="color: var(--shiki-token-punctuation)">,</span></span>
<span><span style="color: var(--shiki-color-text)">		...</span></span>
<span><span style="color: var(--shiki-color-text)">	]</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>
<span></span>

Following parameters should be configured according to data models.

import: the files defined within this parameter will be imported
Types: defined Type will be created with schema set in the imported files.

Main data model schema (`tailordb/<model_name>.cue`)

In Tailor DB, the GraphQL APIs are automatically generated based on schemas.

To familiarize with how a schema looks like, here is the main part of the schema used in Quickstart.

TailorDB Schema Sample

Basic structure of a Schema

The basic schema configuration is composed of three key elements: Type name, Description, and Fields. In this context, Fields represent an object that establish the field names for a given model. In GraphQL terminology, an individual data model is called a Type, which parallels the concept of a Table in relational databases.

Here are the overview of each element.

Name of the Type (Required) : Name of the type is defined as the root key, in the example above "Task".
Description (Required) : Description of the Type. This will appear in GraphQL SDL and GraphQL Playground.
Fields (Required) :fields is an object to define fields within the Type. Schema defines one or more fields. We can define data types, link the resource, add validation, or put constraints to the fields. See Fields for more information.

Permission in a Schema

With TypePermission field, we can control the access to data. We can grant read, write, or delete permissions to specific users, roles, or groups. By default, no one has access to the data. See Permission for more information.

Additional options in Schema

Settings

Enabling advanced features in Settings field allows you to generate additional GraphQL queries. Available features are aggregation of data, bulk upsert, plural form for uncountable nouns and TailorDB CDC. See Advanced API for more information.

Directives

Directive is a GraphQL concept, that provides a way to add additional instructions to GraphQL queries without having to modify the schema. This allows developers to use GraphQL to access the same data in different ways without having to change the underlying data structure. See Advanced API for more information.

Extends

The Extends option enables the extension of the types defined in other sub-graphs, like StateFlow. With this option enabled, CRUD GraphQL queries become available in Tailor DB. See Advanced API for more information.