Generators
Write a table’s migration and its Model from a short description.
Adding a table
Name the Model, and list its columns, with g model:
npx active-record g model Product 'name:string!' 'priceCents:integer!=0' user:references
Wrote migrations/20261108093000_create_products.sql
Wrote src/models/product.ts
Wrote src/db/schema.ts (3 tables) from migrations/
Next: npx active-record migrate
Then apply the migration to your local database:
npx active-record migrate
The table is products, with an id generated in code, created_at, and updated_at.
--id integergives it a key D1 generates instead.--no-timestampsleaves out the timestamps.
Use --remote instead of --local when you deploy.
Writing columns
Each column is name:type, with optional marks:
| Column | Means |
|---|---|
title |
A string, the default type |
email:string!:unique |
Required (NOT NULL), with a unique index |
count:integer!=0 |
Required, with a default of 0 |
settings:json |
JSON, checked by D1 (CHECK (json_valid(settings))) |
user:references |
user_id, pointing at users, indexed; the Model gets user = belongsTo(User) |
The column syntax lists every type.
Changing a table
Write a migration with g migration. It reads what to do from the migration’s name:
npx active-record g migration AddSlugToPosts slug:string:unique # ADD COLUMN, with a unique index
npx active-record g migration RemoveSlugFromPosts slug # DROP COLUMN
npx active-record g migration BackfillSlugs # an empty migration to write yourself
The name can be written AddSlugToPosts or add_slug_to_posts. Apply each migration afterwards, as above.
SQLite can’t add a required column without a default, so the generator refuses one. Give it a default, slug:string!=draft, or leave out the !.
Referencing the same table
g model Category parent:references points parent_id at a parents table and writes parent = belongsTo(Parent), since it can’t know the parent is another category. Edit both files before applying the migration:
-
In the migration, point the column at
categories, and make it optional, since top-level categories have no parent:parent_id TEXT REFERENCES categories (id), -
In the Model, use
Categoryitself, make it optional too, and add the other direction if you want it.
import { belongsTo, hasMany } from "@forestfuture/active-record";
export class Category extends ApplicationRecord {
// foreign key: parentId, from the association's name; optional, since a top-level category has none
parent = belongsTo(Category, { optional: true });
children = hasMany(Category, { foreignKey: "parentId" }); // not the default, categoryId
}
Keeping Models in another folder
By default, Models and application-record.ts go in src/models/. To keep them elsewhere, pass --models to every command:
npx active-record schema --models src/app/models
npx active-record g model Product 'name:string!' --models src/app/models
Keeping the schema current
The generators regenerate src/db/schema.ts themselves. After writing or editing a migration by hand, or adding or renaming a Model, regenerate it:
npx active-record schema
--watchregenerates it whenever a migration or a Model file changes.--checkfails when the committed schema is out of date. Run it in CI.