---
title: Autosaving
description: "Save a record with the records built, changed, or marked for destruction through its associations."
seo:
  description: "Autosave Active Record associations: create records through a hasMany, save a graph with its owner in one batch, save changed records, and markForDestruction."
---

## At a glance

| To                                               | Write                                                           |
| ------------------------------------------------ | --------------------------------------------------------------- |
| create a record with its owner’s key             | `article.comments().create({ body: "…" })`                      |
| build records to save with their owner           | `author.articles().build({ … })`, `author.profile.build({ … })` |
| save the owner and every record built through it | `author.saveOrThrow()`                                          |
| save the loaded records that changed too         | `hasMany(Article, { autosave: true })`                          |
| destroy a record when its owner saves            | `article.markForDestruction()`                                  |

## The Models

The examples use these Models, whose attributes come from their tables through the schema `active-record schema` generates:

```ts author.ts
import { hasMany, hasOne } from "@forestfuture/active-record";
import { ApplicationRecord } from "./application-record";
import { Article } from "./article";
import { Profile } from "./profile";

export class Author extends ApplicationRecord {
  articles = hasMany(Article, { autosave: true }); // saves changed articles with the author
  profile = hasOne(Profile);
}
```

```ts article.ts
import { belongsTo, hasMany } from "@forestfuture/active-record";
import { ApplicationRecord } from "./application-record";
import { Author } from "./author";
import { Comment } from "./comment";

export class Article extends ApplicationRecord {
  author = belongsTo(Author);
  comments = hasMany(Comment, { dependent: "destroy" }); // destroyed with their article
}
```

```ts comment.ts
import { belongsTo } from "@forestfuture/active-record";
import { ApplicationRecord } from "./application-record";
import { Article } from "./article";

export class Comment extends ApplicationRecord {
  article = belongsTo(Article);
}
```

```ts profile.ts
import { belongsTo } from "@forestfuture/active-record";
import { ApplicationRecord } from "./application-record";
import { Author } from "./author";

export class Profile extends ApplicationRecord {
  author = belongsTo(Author);
}
```

```ts schema.ts
// Generated by `active-record schema` from migrations/ — don't edit.
// schema: d6e921e3fa3b

import { defineSchema, type TableAttributes } from "@forestfuture/active-record";
import { d1 } from "@forestfuture/active-record/d1";

/** articles — last changed by 0001_create_tables.sql */
export const articles = {
  id: { type: "string", null: false, generateId: true },
  authorId: { type: "string", null: false },
  title: { type: "string", null: false },
} as const;

/** authors — last changed by 0001_create_tables.sql */
export const authors = {
  id: { type: "string", null: false, generateId: true },
  name: { type: "string", null: false },
} as const;

/** comments — last changed by 0001_create_tables.sql */
export const comments = {
  id: { type: "string", null: false, generateId: true },
  articleId: { type: "string", null: false },
  body: { type: "string", null: false },
} as const;

/** profiles — last changed by 0001_create_tables.sql */
export const profiles = {
  id: { type: "string", null: false, generateId: true },
  authorId: { type: "string", null: false },
  bio: "string",
} as const;

/** The database's adapter and binding, its tables (with their primary keys), and the Models built on them. */
export const schema = defineSchema({
  adapter: d1({ binding: "DB" }),
  tables: {
    articles: { attributes: articles, primaryKey: "id" },
    authors: { attributes: authors, primaryKey: "id" },
    comments: { attributes: comments, primaryKey: "id" },
    profiles: { attributes: profiles, primaryKey: "id" },
  },
  models: { Article: "articles", Author: "authors", Comment: "comments", Profile: "profiles" },
});

declare module "../models/article" {
  interface Article extends TableAttributes<typeof articles, (typeof Article)["attributes"]> {}
}

declare module "../models/author" {
  interface Author extends TableAttributes<typeof authors, (typeof Author)["attributes"]> {}
}

declare module "../models/comment" {
  interface Comment extends TableAttributes<typeof comments, (typeof Comment)["attributes"]> {}
}

declare module "../models/profile" {
  interface Profile extends TableAttributes<typeof profiles, (typeof Profile)["attributes"]> {}
}
```

```sql D1
CREATE TABLE authors (
  id TEXT PRIMARY KEY NOT NULL,
  name TEXT NOT NULL
);
CREATE TABLE profiles (
  id TEXT PRIMARY KEY NOT NULL,
  author_id TEXT NOT NULL REFERENCES authors (id),
  bio TEXT
);
CREATE TABLE articles (
  id TEXT PRIMARY KEY NOT NULL,
  author_id TEXT NOT NULL REFERENCES authors (id),
  title TEXT NOT NULL
);
CREATE TABLE comments (
  id TEXT PRIMARY KEY NOT NULL,
  article_id TEXT NOT NULL REFERENCES articles (id),
  body TEXT NOT NULL
);
```

```sql Postgres
CREATE TABLE authors (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL
);
CREATE TABLE profiles (
  id UUID PRIMARY KEY,
  author_id UUID NOT NULL REFERENCES authors (id),
  bio TEXT
);
CREATE TABLE articles (
  id UUID PRIMARY KEY,
  author_id UUID NOT NULL REFERENCES authors (id),
  title TEXT NOT NULL
);
CREATE TABLE comments (
  id UUID PRIMARY KEY,
  article_id UUID NOT NULL REFERENCES articles (id),
  body TEXT NOT NULL
);
```

## Creating related records

Create a record through a `hasMany`, and it gets the owner’s key:

```ts
import { Article } from "./models/article";

const article = await Article.findByOrThrow({ title: "On Nothing" });
const comment = await article.comments().create({ body: "Lovely." }); // articleId filled in
```

## Saving a graph

Build records through an association, then save the owner, and they’re saved with it:

```ts
import { Author } from "./models/author";

const author = Author.build({ name: "Sam" });
author.articles().build({ title: "Getting started" });
author.articles().build({ title: "Going further" });
author.profile.build({ bio: "Writer" });
await author.saveOrThrow(); // the author, both articles, and the profile, in one batch
```

- The built records are validated with the owner. An invalid article makes the author invalid (“Articles is invalid”), with its own errors on the article. To validate the records an association loaded too, use [`validatesAssociated`](/validations#validating-associated-records).
- Each built article’s `author` is the owner, without a query, even before either is saved.
- When the owner’s key is generated in code, as here, everything is written in one atomic batch. Records on [another database](/several-databases#associating-models-on-different-databases) are written there separately.

:::warning[Keys D1 generates]
When D1 generates the key, with an `INTEGER PRIMARY KEY`, the key doesn’t exist until the owner is written. So the owner is written first, and its records follow in the next batch, a level at a time. The batches aren’t atomic together: if a record fails at the second level, the save throws with the owner already saved. Generate keys in code wherever a graph must save all at once.
:::

## Saving changed records

Declare an association with `autosave: true`, as `Author`’s `articles` does, to save the changes to its loaded records with their owner:

```ts
import { Author } from "./models/author";

const author = await Author.findByOrThrow({ name: "Jane" });
const articles = await author.articles().toArray();

for (const article of articles) article.title = article.title.toUpperCase();
await author.saveOrThrow(); // every article that changed, in one batch
```

- By default, only new records are saved with their owner.
- Saving the author saves each article that changed, in the same atomic batch. Unchanged articles aren’t validated or written.
- Only the records the association holds count: those it loaded, and those built through it. A record you found with a query of its own isn’t saved.
- The changed records are validated with the owner. An invalid one’s errors are copied to the owner under the association’s name: an article with a blank title gives the author an `articles.title` error, “Articles title can’t be blank”.
- `autosave: true` works on a `hasOne` and a `belongsTo` too. A `belongsTo`’s record is saved before its owner.

## Removing records on save

Mark a record with `markForDestruction()` to destroy it when its owner is saved:

```ts
import { Author } from "./models/author";

const author = await Author.findByOrThrow({ name: "Jane" });
const articles = await author.articles().toArray();

for (const article of articles) {
  if (article.title.startsWith("Draft")) article.markForDestruction();
}
await author.saveOrThrow(); // destroys the drafts, with their comments
```

- Marking writes nothing, and the marked articles stay in `author.articles()` until the author is saved. Then each is destroyed with its callbacks and `dependent` strategies, in the same batch as the author, and leaves the association. Changed articles are saved after the destroys.
- `isMarkedForDestruction()` reads the mark, and `reload()` clears it. A marked record that was never saved is dropped from the association, and nothing is written for it.
- Through a `belongsTo`, the owner’s foreign key is set to `null`, and the owner is written before its record is destroyed.
- If a marked record refuses to be destroyed, because its `beforeDestroy` aborts or a `restrictWithError` strategy stops it, nothing is written. `save()` returns `false`, and `saveOrThrow()` throws `RecordNotDestroyed`. The marked record holds the reason, in `abortReason` or `errors`.

:::note
A mark only counts through an association declared `autosave: true`.
:::

## Not built yet

These features aren’t in Active Record yet. The code shows the shape they’re likely to take.

- **Autosaving through an association through another** ([#450](https://github.com/forestfuture/active-record/issues/450)): `articles = hasMany(Article, { through: "taggings", autosave: true })`, which saves the tag’s changed articles with it.
- **Never autosaving** ([#378](https://github.com/forestfuture/active-record/issues/378)): `articles = hasMany(Article, { autosave: false })`, which never saves the association’s records with the owner, not even new ones.
- **Numbered autosave errors** ([#379](https://github.com/forestfuture/active-record/issues/379)): `hasMany(Article, { autosave: true, indexErrors: true })`, which names a copied error by the record’s position, `articles[1].title`.

> **Compared with Rails**
>
> `autosave: true`, `markForDestruction`, and the copied errors work as in Rails. Rails destroys a marked `belongs_to` record before it saves the owner. Here the owner is written first, so a foreign key constraint doesn’t refuse the delete. When a marked record refuses to be destroyed, Rails raises from `save` for a `has_many`, and saves the owner anyway for a `has_one` or `belongs_to`. Here the save is refused the same way for every association.
