Skip to content

Schemas

The schema block inside an entity defines the structure of its data: primary key, fields, and relationships.

entity "Cat" {
    schema {
        pk "id" type="int"
        field "name" type="string"
        field "age" type="int" optional=true
        field "photo" type="file"
        has-many "kittens" as="Cat" alias="mother_id"
        has-one "owner" as="User" optional=true
        belongs-to "breed" as="Breed" on="breed_id"
    }
}

Primary Key (pk)

Defines the primary key column. Every table can have at most one primary key.

Attribute Type Required Description
name string ✓ Column name (e.g., "id")
type string ✓ One of: int, string (see supported types below)

Example:

pk "id" type="int"
  • type="int" – Auto‑incrementing integer primary key.
  • type="string" – Text primary key (must be provided by the client).

Important: If an entity does not define a primary key (pk), Terranova will not automatically generate DELETE or UPDATE endpoints for that entity. The auto‑generated CRUD will still support POST (create) and GET (list), but explicit updates and deletes require a primary key.

Fields (field)

Defines a column in the database table.

Attribute Type Required Default Description
name string ✓ – Column name
type string ✓ – Data type (see table below)
optional bool false Allows NULL values
unique bool false Enforces uniqueness

Supported Types

Terranova Type SQLite Type Description
int INTEGER 64‑bit signed integer
float REAL 64‑bit floating point
string TEXT Variable‑length string
blob BLOB Binary large object
file BLOB File content stored as BLOB
date DATE Date only (ISO8601 text)
datetime DATETIME Date and time (ISO8601 text)
bool BOOL Boolean (stored as 0/1 integer)

Relationships

Relationships connect entities. They are documented in detail on the Relationships page. Here is a quick reference:

has-many

One‑to‑many relationship (parent → children).

has-many "Comment" as="comments" on-delete="cascade" optional=true

has-one

One‑to‑one relationship.

has-one "Profile" as="profile" on-delete="restrict"

belongs-to

Inverse side of a relationship (child → parent). The on attribute specifies the primary key column name in the parent entity (defaults to "id"). The foreign key column in the child table is automatically named {parent_lowercase}_id (e.g., user_id).

belongs-to "User" as="author" on="id" optional=false
Attribute Type Required Default Description
name string ✓ – Parent entity name
as string ✓ – Relationship name
alias string – Optional alias for the foreign key column
on string "id" Primary key column name in the parent table
optional bool false Whether the foreign key can be NULL

Example: If parent User has primary key user_id (instead of id), specify:

belongs-to "User" as="author" on="user_id"

This creates a foreign key column author_id in the child table that references User(user_id).

Complete Example

entity "Post" {
    schema {
        pk "id" type="int"
        field "title" type="string"
        field "content" type="string"
        field "published_at" type="datetime" optional=true
        field "cover_image" type="file"
        has-one "author" as="User" optional=false
        has-many "comments" as="Comment" on-delete="cascade"
        belongs-to "category" as="Category" optional=true
    }
}

What Terranova Does With the Schema

  • Database table creation – Creates or alters the table based on the schema.
  • Auto‑generated operations – DELETE and UPDATE endpoints are only generated if a pk is defined.

See Also