Getting Started

What are relations?

Relations help you work with related models easily. There are several types of relations:

Relation options

Several options can be specified for relations:

• eager: boolean - If set to true, the relation will always be loaded with the main model when using find* methods or QueryBuilder on this model.
• cascade: boolean | ("insert" | "update")[] - If set to true, the related object will be inserted and updated in the database. You can also specify an array of cascade options.
• onDelete: "RESTRICT"|"CASCADE"|"SET NULL" - Specifies how the foreign key should behave when the referenced object is deleted.
• nullable: boolean - Indicates whether this relation's column is nullable or not. By default, it is nullable.
• orphanedRowAction: "nullify" | "delete" | "soft-delete" | "disable" - Controls what happens to child rows in the database when the parent is saved (with cascading enabled) but no longer contains the child rows. Options include:
  • delete: Removes these child rows from the database.
  • soft-delete: Marks child rows as soft-deleted.
  • nullify: Removes the relation key.
  • disable: Keeps the relation intact, requiring manual repository use for deletion.

Cascades

Cascades example:

import { Model, PrimaryKeyColumn, Column, ManyToMany } from "alapa";
import { Question } from "./Question";

@Model()
export class Category {
  @PrimaryKeyColumn()
  id: number;

  @Column()
  name: string;

  @ManyToMany((type) => Question, (question) => question.categories)
  questions: Question[];
}

import { Model, PrimaryKeyColumn, Column, ManyToMany, JoinTable } from "alapa";
import { Category } from "./Category";

@Model()
export class Question {
  @PrimaryKeyColumn()
  id: number;

  @Column()
  title: string;

  @Column()
  text: string;

  @ManyToMany((type) => Category, (category) => category.questions, {
    cascade: true,
  })
  @JoinTable()
  categories: Category[];
}

const category1 = new Category();
category1.name = "ORMs";

const category2 = new Category();
category2.name = "Programming";

const question = new Question();
question.title = "How to ask questions?";
question.text = "Where can I ask ORM-related questions?";
question.categories = [category1, category2];
await dataSource.manager.save(question);

In this example, category1 and category2 are automatically inserted because we set cascade to true.

Cascade Options

The cascade option can be set as a boolean or an array of cascade options ("insert" | "update" | "remove" | "soft-remove" | "recover")[]

For example:

@Model(Post)
export class Post {
  @PrimaryKeyColumn()
  id: number;

  @Column()
  title: string;

  @Column()
  text: string;

  @ManyToMany((type) => PostCategory, { cascade: true })
  @JoinTable()
  categories: PostCategory[];

  @ManyToMany((type) => PostDetails, (details) => details.posts, {
    cascade: ["insert"],
  })
  @JoinTable()
  details: PostDetails[];

  @ManyToMany((type) => PostImage, (image) => image.posts, {
    cascade: ["update"],
  })
  @JoinTable()
  images: PostImage[];

  @ManyToMany((type) => PostInformation, (information) => information.posts, {
    cascade: ["insert", "update"],
  })
  @JoinTable()
  informations: PostInformation[];
}

@JoinColumn Options

@JoinColumn defines which side of the relation contains the join column with a foreign key and allows customizing column names.

Example:

@ManyToOne((type) => Category)
@JoinColumn()
category: Category;

This creates a categoryId column. To customize the name:

@ManyToOne((type) => Category)
@JoinColumn({ name: "cat_id" })
category: Category;

To reference a column other than the primary column:

@ManyToOne((type) => Category)
@JoinColumn({ referencedColumnName: "name" })
category: Category;

@JoinTable Options

@JoinTable is used for many-to-many relations and describes the join columns in the junction table. You can customize column names and the table name:

@ManyToMany((type) => Category)
@JoinTable({
  name: "question_categories",
  joinColumn: {
    name: "question",
    referencedColumnName: "id",
  },
  inverseJoinColumn: {
    name: "category",
    referencedColumnName: "id",
  },
})
categories: Category[];

If the destination table has composite primary keys, specify an array of properties in @JoinTable.