Как описывать внешние ключи, индексы и связи?
На этой странице
Внешний ключ обеспечивает существование связанной строки, индекс ускоряет определённые запросы, а описание связи помогает Drizzle загружать связанные данные.
Вопрос
Как описать в Drizzle внешние ключи, индексы и связи между таблицами? Чем relations() отличается от внешнего ключа?
Таблица задач
import { relations } from "drizzle-orm";
import {
index,
integer,
pgTable,
timestamp,
varchar,
} from "drizzle-orm/pg-core";
export const tasks = pgTable(
"tasks",
{
id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
userId: integer("user_id")
.notNull()
.references(() => users.id, { onDelete: "cascade" }),
title: varchar("title", { length: 200 }).notNull(),
createdAt: timestamp("created_at", { withTimezone: true })
.notNull()
.defaultNow(),
},
(table) => [
index("tasks_user_id_idx").on(table.userId),
index("tasks_created_at_idx").on(table.createdAt),
],
);Внешний ключ
.references(() => users.id, { onDelete: "cascade" })PostgreSQL не позволит записать задачу для несуществующего пользователя.
onDelete: "cascade" означает: при удалении пользователя удалить и его задачи. Это подходит не всегда. Возможны варианты:
restrict— запретить удаление родителя;set null— очистить ссылку, если столбец допускаетnull;cascade— удалить зависимые строки.
Выбор является частью требований, а не технической мелочью.
Индекс
index("tasks_user_id_idx").on(table.userId)Он полезен для частого запроса:
SELECT * FROM tasks WHERE user_id = 42;Индекс ускоряет чтение, но занимает место и замедляет вставку и изменение. Не добавляй индекс к каждому столбцу без причины.
Связи Drizzle
export const usersRelations = relations(users, ({ many }) => ({
tasks: many(tasks),
}));
export const tasksRelations = relations(tasks, ({ one }) => ({
user: one(users, {
fields: [tasks.userId],
references: [users.id],
}),
}));Описание связи не создаёт внешний ключ. Внешний ключ задаётся отдельно через .references() и попадает в PostgreSQL.
Что важно помнить
- Внешний ключ (
.references()) — ограничение PostgreSQL, которое не даёт сослаться на несуществующую строку. onDelete: "cascade"удаляет зависимые строки,"restrict"запрещает удаление — выбор зависит от требований.- PostgreSQL не создаёт индекс на столбце внешнего ключа автоматически — его добавляют отдельно.
- Каждый индекс ускоряет чтение, но замедляет запись и занимает место.
relations()нужен только Drizzle дляdb.queryи в миграции не попадает.
Мини-шпаргалка
- Внешний ключ защищает целостность данных.
onDeleteвыбирается по требованиям.- Индекс ускоряет подходящие условия и сортировки.
- Индексы имеют цену при записи.
relations()помогает ORM, но не заменяет ограничение базы.
Документация
Drizzle: PostgreSQL column types, Drizzle: Indexes & Constraints, Drizzle: Relations, PostgreSQL: Indexes.