Nested create with Drizzle relations

Drizzle nested create in NestJS works through writableRelations: list a relation there, put the related rows in the create body under the relation's name, and the package writes the parent and its children in one transaction. Every write method also takes options.relations and returns its rows with those relations loaded, and attach, detach and sync change many-to-many links with set-based statements.

How do I get a created row back with its relations?Copy Anchor Link

Pass relations (and counts, see Aggregates) as you would on find:

const post = await posts.create(
  { title: 'Hello', author_id: 2, status: 'draft' },
  { relations: ['author', 'tags'] },
);
post.author.name; // 'Bob'
post.tags;        // []

That is one INSERT plus one query per relation. A mass write loads the relations of every row it wrote in one query per relation too, so massCreate of 10 posts with relations: ['author'] is an INSERT and one SELECT, not ten.

const created = await posts.massCreate(dtos, { relations: ['author'], counts: ['tags'] });

These methods load relations onto what they return:

The relation paths are checked against loadableRelations before anything is written, so a bad path is a 400 and leaves the table untouched.

How do I create a row with its children in one call?Copy Anchor Link

Allow the relation, then send the children in the body.

DrizzleCrudModule.forFeature([{
  service: AuthorsService,
  table: authors,
  config: {
    relations: {
      posts: { table: posts, type: 'hasMany', foreignKey: 'author_id' },
    },
    writableRelations: ['posts'],
  },
}]);

const author = await authors.create(
  {
    name: 'Dee',
    email: 'dee@x.io',
    posts: [
      { title: 'First', status: 'draft' },
      { title: 'Second', status: 'draft' },
    ],
  },
  { relations: ['posts'] },
);

What shapes does a nested body take?Copy Anchor Link

The body value depends on the relation type:

A few rules apply to every shape:

• Nested writes run on create only, and go one level deep.
• Only the related table's own columns are written, never its soft delete column. Other keys in a child object are dropped.
• The timestamps and the tenant scope are set on a child row when the related table has those columns.
• A relation key set to null is skipped.
• A wrong shape (an object for has-many, an array for belongs-to) is a 400.
• On MySQL, which has no RETURNING, a nested create is a 400.

What if writableRelations is not set?Copy Anchor Link

Then nested writes are off. A relation key in the body is left alone and Drizzle ignores it, which is how 3.4 behaved. With the list set, a relation key that is not in it is a 400, the same way writableColumns treats a column. A trusted server-side call can pass skipAllowlists: true to write any declared relation.

How do I attach or detach many-to-many rows?Copy Anchor Link

Call attach, detach or sync with the row's id, the relation name and the related ids:

await posts.attach(2, 'tags', [1, 2]);         // link tags 1 and 2
await posts.detach(2, 'tags', [1]);            // unlink tag 1
await posts.detach(2, 'tags');                 // unlink every tag
const post = await posts.sync(2, 'tags', [2]); // links are exactly [2] now
post.tags; // [{ id: 2, name: 'tech' }]

Each method returns Promise<T>: the row with that relation loaded, plus anything in options.relations. Each runs in one transaction and is set based whatever the number of ids: one SELECT checks the targets exist, one finds the links already there, and one INSERT adds the rest (sync adds one DELETE). Duplicates in the list are ignored. The related rows themselves are never changed or deleted.

With global hooks on, they raise attach, detach and sync events.

What errors can attach, detach and sync return?Copy Anchor Link

When writableRelations is unset, attach, detach and sync work on any many-to-many relation.

Common questionsCopy Anchor Link

Next stepsCopy Anchor Link