Upgrading
Move an app up one release at a time, starting from the release you’re on.
Upgrading from 0.7 to 0.8
In 0.8, a belongsTo requires its record, a batch prepares its writes in a callback, a new record’s changes run from its defaults, a hasOne’s new record replaces its old one, a hasMany gives its records its own key, a bulk write gives its Relation’s values over yours, the generated schema is a defineSchema call and reads a DATE column as a date, and serialize can give bytes. Upgrade in nine steps.
Marking optional associations
Saving now fails with “must exist” when a belongsTo points at nothing. Add optional: true to each one whose foreign key can be null:
import { belongsTo } from "@forestfuture/active-record";
export class Category extends ApplicationRecord {
parent = belongsTo(Category, { optional: true });
}
A record built through its owner’s hasMany or hasOne passes without it.
Reading a new record’s changes
A new record’s changes(), changed(), and isChanged() no longer list its declared defaults or generated id, and savedChanges() after a create leaves out the defaults it kept. Check code that reads them on new records, such as a callback that tests isChanged() before an insert. Use isNewRecord() to ask whether a record is new.
Preparing batch writes in a callback
Pass batch and db.batch a callback that returns the writes, instead of an array:
import { batch } from "@forestfuture/active-record";
await batch((b) => [b.save(user), b.deleteAll(Post.where({ userId: user.id }))]);
Records’ toSave() and toDestroy(), and the to… methods such as toInsert and toDeleteAll, are gone. Call b.save, b.destroy, b.insert, and the rest instead.
Replacing a hasOne’s record
Building or creating a record through a saved owner’s hasOne now removes the old record, by the association’s dependent strategy. Without one, the old record’s foreign key is set to NULL, which fails on a NOT NULL column. Set dependent: "destroy" or "delete" where the old record should go instead. Building twice through an unsaved owner now saves only the last record. See Replacing the record.
Checking keys given through a hasMany
A record built, created, or inserted through a hasMany now always gets its owner’s key, as one built through a hasOne already did. A foreign key you pass, such as user.posts().build({ userId: otherId }), is replaced. To write a record for another owner, build it through that owner, or through the Model: Post.build({ userId: otherId }).
Checking values given to bulk writes
insert, insertAll, upsert, and upsertAll through a Relation now write its equality conditions, its createWith attributes, and its default scope’s values over the attributes you pass. So Post.where({ userId: 1 }).insert({ title: "Hi", userId: 2 }) now writes userId: 1. Check bulk writes that pass a value their Relation also sets. To write the value you pass, leave the condition out. To write over a default scope’s value, start from Post.unscoped(). build and create still use the values you pass.
Regenerating the schema
Run schema in your project’s folder:
npx active-record schema
The generated schema.ts now declares schema with defineSchema({ … }), which an enum’s scopes need. Until you regenerate it, active-record schema --check reports it as out of date.
Reading DATE columns
The generated schema now reads a DATE column as a date, a day’s text such as "2026-01-02", where it was a datetime. Update code that reads one as a Date, or keep the attribute a datetime with an override:
import { ApplicationRecord } from "./application-record";
export class Event extends ApplicationRecord {
static override attributes = { startsOn: "datetime" } as const;
}
On D1, a DATE column that a datetime wrote holds a date and time, such as "2026-01-02T00:00:00.000Z", and a date can’t read it. Count the rows whose time isn’t midnight:
SELECT count(*) FROM events
WHERE length(starts_on) > 10 AND substr(starts_on, 11) <> 'T00:00:00.000Z';
If there are none, keep only each day:
UPDATE events SET starts_on = substr(starts_on, 1, 10) WHERE length(starts_on) > 10;
Postgres stores a date without a time, so its rows need no change.
A TIME column is now a time, where it was a string, and reads as "09:30:00". A NUMERIC or DECIMAL column is now a decimal, where it was an error.
Typing serialized values
typeForAttribute(name).serialize now returns string | number | Uint8Array | null, since a binary attribute is stored as bytes. Code that gives its result a narrower type, such as string | number | null, needs the wider one.
Upgrading from 0.6 to 0.7
In 0.7, the adapters ship inside @forestfuture/active-record, so an app on D1 installs one package. Upgrade in four steps.
Replacing the D1 package
Remove the D1 package, then update the core:
npm uninstall @forestfuture/d1-record
npm install @forestfuture/active-record@^0.7.0
Changing imports
Import what opens D1 from the core’s /d1 entry:
import { connect, d1, withSession } from "@forestfuture/active-record/d1";
Everything else still comes from @forestfuture/active-record. If your Vitest config inlines the D1 adapter (server.deps.inline), inline @forestfuture/active-record instead.
Writing active-record.jsonc
Run init in your project’s folder:
npx active-record init
It writes active-record.jsonc, naming each database in your Wrangler config’s d1_databases and its adapter:
{
"$schema": "./node_modules/@forestfuture/active-record/config-schema.json",
"databases": {
"DB": { "adapter": "d1" },
},
}
Every active-record command reads it. Each database’s migrations folder stays in your Wrangler config. --adapter is gone, and --config now names this file. If you used --config to name a Wrangler config in another folder, name it in the database’s entry with wranglerConfig instead.
Regenerating the schema
Regenerate your schema:
npx active-record schema
Its import changes to @forestfuture/active-record/d1. Until you regenerate it, active-record schema --check reports it as out of date.
Upgrading from d1-record 0.5 to 0.6
In 0.6, the library is two packages. @forestfuture/active-record is the core: Models, Relations, validations, callbacks, and associations. @forestfuture/d1-record is its adapter for D1. Upgrade in four steps.
Installing both packages
Install the core beside the adapter:
npm install @forestfuture/active-record@^0.6.0 @forestfuture/d1-record@^0.6.0
Both packages share a version, so keep them on the same one.
Changing imports
Import from the core everything that isn’t about D1. Import from the adapter what opens D1:
import {
batch,
belongsTo,
hasMany,
Model,
RecordNotFound,
withDatabase,
} from "@forestfuture/active-record";
import { connect, d1, withSession } from "@forestfuture/d1-record";
| Package | What it holds |
|---|---|
@forestfuture/active-record |
Models, Relations, batch, withDatabase, sql, and every error but one |
@forestfuture/d1-record |
connect, Database, withSession, NoSession, d1, and D1’s QueryEvent |
d1-record re-exports nothing of the core, so an import of Model from it fails.
Regenerating the schema
Run the schema command under its new name:
npx active-record schema
The generated schema now names its adapter, adapter: d1({ binding: "DB" }), where it named only the binding. Your base class needs no change.
Running active-record
The command is now active-record, or ffar for short. Swap it in your scripts and CI:
| Before | Now |
|---|---|
npx d1-record schema |
npx active-record schema |
npx d1-record g model … |
npx active-record g model … |
npx d1-record console |
npx active-record console |
It also applies migrations through your project’s Wrangler, with npx active-record migrate. See Command line.
Updating for the other changes
- Write results:
insert,insertAll,upsert, andupsertAllresolve to{ rowsAffected, rows }, where they resolved to D1’smeta.rowsholds each written row’s primary key, or the attributes itsreturningoption names. UserowsAffectedformeta.changes, androws[0]?.idformeta.last_row_id. A statement inbatchresolves to the same. - The base error is
ActiveRecordError, where it wasD1RecordError. toSql()with no database: on a Model with no generated schema, outsidewithDatabase, it throwsNoDatabase. Use adb(db.model(Post).toSql()), or a Model built on your base class.- D1’s
metais still on everyonQueryevent. - The agent skill is now
active-record. Install it again withnpx skills add forestfuture/active-record.