Skip to content
Active Record
Esc
↑↓navigate↵open⌘Jpreview
On this page

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, and upsertAll resolve to { rowsAffected, rows }, where they resolved to D1’s meta. rows holds each written row’s primary key, or the attributes its returning option names. Use rowsAffected for meta.changes, and rows[0]?.id for meta.last_row_id. A statement in batch resolves to the same.
  • The base error is ActiveRecordError, where it was D1RecordError.
  • toSql() with no database: on a Model with no generated schema, outside withDatabase, it throws NoDatabase. Use a db (db.model(Post).toSql()), or a Model built on your base class.
  • D1’s meta is still on every onQuery event.
  • The agent skill is now active-record. Install it again with npx skills add forestfuture/active-record.

Last updated on