Models & Fields

Think of a model as a structured description of a database table. Instead of writing raw CREATE TABLE SQL, you define your table in TypeScript with full type safety, autocomplete, and validation. Zanith reads this definition at runtime and uses it to build queries, enforce types, and manage relationships.

Every model has these parts. Some are required, others are optional but recommended.

1. 01

   name

   The model name in PascalCase (e.g. 'User', 'BlogPost'). Used in code and error messages.

2. 02

   table

   The actual PostgreSQL table name (e.g. 'users', 'blog_posts'). This is what appears in your database.

3. 03

   fields

   The columns. Each has a type (string, int, boolean...), optional modifiers (nullable, unique, default...), and maps to a database column.

4. 04

   relations (optional)

   How this model connects to other models — belongsTo, hasMany, hasOne, manyToMany.

5. 05

   indexes & constraints (optional)

   Database indexes for performance and unique constraints for data integrity.

6. 06

   comment & meta (optional)

   Documentation and organizational metadata. Comments appear in the schema graph and can power admin UIs.

Here's a real-world Product model with every feature demonstrated:

1import { defineModel } from 'zanith';
2 
3const Product = defineModel((m) => ({
4  name: 'Product',
5  table: 'products',
6 
7  fields: {
8    ...m.id(),                          // uuid primary key
9    ...m.timestamps(),                  // createdAt + updatedAt
10    name: m.string(),                   // required string (TEXT)
11    description: m.text().nullable(),   // optional long text
12    price: m.float(),                   // decimal number
13    sku: m.string().unique(),           // unique constraint
14    inStock: m.boolean().default(true), // boolean with default
15    metadata: m.json().nullable(),      // JSONB column
16    categoryId: m.uuid().index(),       // indexed foreign key
17  },
18 
19  relations: {
20    category: m.belongsTo(Category, {
21      field: 'categoryId',
22      references: 'id',
23    }),
24  },
25 
26  indexes: [
27    m.index((f) => [f.sku]),            // explicit index
28  ],
29 
30  constraints: [
31    m.unique((f) => [f.name, f.categoryId]), // composite unique
32  ],
33 
34  comment: 'Product catalog',
35  meta: { module: 'inventory', owner: 'backend-team' },
36}));

Every field starts with a type. Here's what's available and what each maps to in PostgreSQL and TypeScript:

Modifiers change how a field behaves. Chain them after the type:

Zanith automatically converts between JavaScript conventions (camelCase) and PostgreSQL conventions (snake_case):

Override with table: "custom_table_name" on the model or .map("custom_column") on a field.