---
title: Coming from Rails
description: "Bring what you know from Rails’ Active Record, and learn what works differently."
seo:
  description: "Active Record for Cloudflare Workers compared with Rails’ Active Record: what carries over, and what differs, from camelCase attributes to OrThrow methods."
---

:::tip
Models, validations, callbacks, associations, scopes, and dirty tracking all follow Rails’ Active Record, down to the default error messages.
:::

## Querying from the Model

```ts
// Rails: User.where(active: true)
const users = await User.where({ isActive: true }).toArray();
```

A Model queries by itself. The binding in the generated schema its base class holds plays the part of `connects_to`.

A Worker serves many requests at once from one isolate, so nothing about a request is stored on the class. For a D1 Session or per-request logging, run the request in [`withDatabase`](/connecting#using-the-requests-database). A record keeps the database it came from.

## Naming things

Most names are Rails’ own, in camelCase:

| Rails                                    | Active Record for Workers                         |
| ---------------------------------------- | ------------------------------------------------- |
| `created_at` (attribute)                 | `createdAt`, mapped to `created_at`               |
| `foreign_key: :user_id`                  | `foreignKey: "userId"`                            |
| `save!`, `create!`, `find_by!`           | `saveOrThrow`, `createOrThrow`, `findByOrThrow`   |
| `new_record?`, `persisted?`              | `isNewRecord()`, `isPersisted()`                  |
| `find_or_create_by(name:) do … end`      | `findOrCreateBy({ name }, (tag) => …)`            |
| `empty?`, `any?`                         | `isEmpty()`, `hasAny()`                           |
| `many?`, `one?`                          | `hasMoreThanOne()`, `hasExactlyOne()`             |
| `unscope(:order, where: :role)`          | `unscope("order", { where: "role" })`             |
| `changed?`, `saved_change_to_email?`     | `isChanged()`, `hasSavedChangeTo("email")`        |
| `rails generate model Post title:string` | `npx active-record g model Post title:string`     |
| `db/schema.rb`, `rails db:schema:dump`   | `src/db/schema.ts`, `npx active-record schema`    |
| `class Post < ApplicationRecord`         | `class Post extends ApplicationRecord`            |
| `scope :active, -> { … }`                | `static active = this.scope((q) => …)`            |
| `has_many :posts, dependent: :destroy`   | `posts = hasMany(Post, { dependent: "destroy" })` |
| `post.author = user`                     | `post.author.set(user)`                           |
| `build_profile`                          | `user.profile.build()`                            |
| `user.profile = profile`                 | `await user.profile.set(profile)`                 |
| `reload_author`                          | `post.reloadAssociation("author")`                |
| `throw :abort`                           | `throw abort("reason")`                           |
| `to_json`                                | `toJSON()`                                        |

Attributes, conditions, and association keys all name attributes, in camelCase. Column names only appear inside `sql` fragments. Foreign keys follow Rails’ conventions, so `User`’s `has_many` uses `userId`.

## Declaring Models

Migrations define the columns, and a Model declares only behavior. Where Rails reads the columns when the app runs, this library reads them into `src/db/schema.ts` when you run `active-record schema` or a generator, so TypeScript knows every attribute’s type.

A Model names its table, since TypeScript can’t derive a class’s types from its name. Scopes are statics, and validations and callbacks go in a `static {}` block:

```ts
import { ApplicationRecord } from "./application-record";

// Rails:
//   class Product < ApplicationRecord
//     scope :in_stock, -> { where(available: true) }
//     validates :name, presence: true
//   end
export class Product extends ApplicationRecord {
  static override attributes = { available: "boolean" } as const;
  static inStock = this.scope((q) => q.where({ available: true }));

  static {
    this.validates("name", { presence: true });
  }
}
```

## Writing atomically

There’s no `transaction do … end`, since D1 can’t keep a transaction open across awaits. Use [`batch((b) => [...])`](/batches) instead. In its callback, `b.save(user)`, `b.destroy(post)`, and bulk writes like `b.updateAll(…)` prepare writes. They’re sent atomically once the callback returns. Generating keys in code makes whole graphs of new records atomic too. See [D1’s limits](/d1).

## Primary keys

:::warning[Keys are UUIDs, not integers]
`g model` gives each table a `TEXT` `id` generated in code, which is what makes those batches atomic. `--id integer` gives you integer keys that D1 assigns, without that guarantee.
:::

## Generating code

The generators follow `rails generate model` and `rails generate migration`. A column can also have a literal default, `count:integer!=0`, which Rails’ generators can’t express. See [Generators](/generators).

## Smaller differences

- `insert` and `insertAll` raise on duplicates. Skipping them is opt-in, with `{ onDuplicate: "skip" }`.
- `insert` fills in declared defaults, since that’s where keys are generated.
- `merge` replaces the order rather than appending to it.
- `merge` of another Model needs a join to it, and takes only its conditions and order. Anything else throws `IncompatibleRelation` when you write the query.
- `find(1, 2)` on a `hasMany` join returns each record once.
- `distinct()` with an order on a joined Model throws `IncompatibleRelation` on every database. Rails leaves it to the database, and only Postgres refuses it.
- `last()` can’t reverse an `sql` fragment order, and throws `IrreversibleOrder`, rather than trying to parse SQL.
- `find(1, 1)` always returns an array, so its return type follows its arguments.
- `dependent:` strategies run after the owner’s `beforeDestroy` callbacks, wherever they’re declared, so an `abort()` always protects the records.
- Records in a batch run all their before-callbacks before any write, and their after-callbacks after all of them.
- Scopes preloaded with `limit` throw, where Rails silently gives wrong results.

## Not built yet

`has_many :through`, `where` keyed by an association, `where.missing`, `eager_load`, single-table inheritance, `destroy_async`, and error messages in other languages.
