Kora/developer documentation/Models

Models

Database tables for your module and the methods to read and write them.

A model is one database table. Kora creates the table on startup and gives you methods to read and write it. Put models in src/models/.

modules/example/src/models/Item.js

import { Models } from "#kora/modules";

export class Item extends Models {
    constructor(kora) {
        super(kora, {
            name: "example_items",
            search: ["name", "identifier"],
            filters: ["active"]
        });
    }

    schema() {
        return {
            identifier: { type: "string", required: true, unique: true },
            name: { type: "string", required: true },
            description: "text",
            quantity: { type: "integer", default: 1 },
            price: { type: "float", default: 0 },
            active: { type: "boolean", default: true },
            metadata: "json",
            expires_at: "date"
        };
    }
}

Get it from anywhere with this.kora.modules.models.get("example", "example_items").

Options

Key	Default	What it does
`name`	Required	The model name and table name. Prefix it with your module ID.
`search`	`[]`	Columns that `page({ search })` matches against, ignoring case.
`filters`	`[]`	Query string keys that `query()` turns into `where` conditions.
`indexes`	`[]`	Extra Sequelize indexes.
`dynamic`	`false`	Store fields that are not in the schema in a JSON `options` column.

Fields

A field is a type name, or an object with type, required, unique and default.

Type	SQL
`string`	`VARCHAR(255)`
`text`	`TEXT`
`integer`	`INTEGER`
`bigint`	`BIGINT`
`float`	`FLOAT`
`boolean`	`BOOLEAN`
`date`	Timestamp
`json`	`JSON`
`uuid`	`UUID`

Every table also gets an id. An unknown type stops the module from loading.

Methods

Method	Returns
`create(values)`	The new row.
`find(id)`	The row with that `id`, or `null`.
`require(id)`	The row with that `id`. Throws a `404` if missing.
`get(where)`	The first matching row, or `null`.
`list(where, options)`	All matching rows. `options` goes to Sequelize, such as `order`.
`count(where, options)`	How many rows match.
`edit(where, values)`	Updates matching rows.
`delete(where)`	Deletes matching rows and returns how many.
`page(options)`	`{ rows, total }` for a list page.
`query(request.query)`	Turns a query string into options for `page()`.

this.op is Sequelize's Op, for conditions like { created_at: { [this.op.gte]: date } }.

Paging

async GET(request) {
    const items = this.kora.modules.models.get(this.module, "example_items");
    return items.page(items.query(request.query));
}

query() reads search, limit, offset and your filters. page() sorts newest first unless you pass order.

Errors

A duplicate value in a unique field throws with status 409. A missing required field throws with status 400. Inside a route, both are sent back to the caller as { error }.

PreviousTooling NextHandlers