---
title: Upgrading
description: "Move an app up one release at a time, starting from the release you’re on."
seo:
  description: "Upgrade an Active Record app one release at a time, from d1-record 0.5 to Active Record 0.8, with the code and schema changes each release needs."
---

## 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`:

```ts
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:

```ts
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](/associations#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:

```sh
npx active-record schema
```

The generated `schema.ts` now declares `schema` with `defineSchema({ … })`, which an [enum](/enums#declaring-enums)’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`](/attribute-types#storing-exact-numbers-days-and-times), 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:

```ts
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:

```sql
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:

```sql
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`](/attribute-types#storing-exact-numbers-days-and-times), 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](/attribute-types#storing-bytes) 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:

```sh
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:

```ts
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:

```sh
npx active-record init
```

It writes `active-record.jsonc`, naming each database in your Wrangler config’s `d1_databases` and its adapter:

```jsonc
{
  "$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`](/command-line#declaring-your-databases) instead.

### Regenerating the schema

Regenerate your schema:

```sh
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:

```sh
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:

```ts
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:

```sh
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](/command-line#active-record-migrate).

### 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`.
