DT
Drizzle Team•5w ago
hidoos

Drizzle ORM: Does `.references()` Automatically Infer Relations for Query API or Is Manual `relation

I'm trying to understand the exact relationship between the references() method and relation definitions in the Drizzle ORM. I've noticed some discrepancies between the code requirements and what Drizzle Studio displays. Here is my original schema code without any explicit relations: 
export const countries = pgTable("countries", {
  id: serial('id').primaryKey(),
  name: varchar('name', {length: 256}).notNull(),
});

export const cities = pgTable('cities', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 256 }),
  countryId: integer('country_id').references(() => countries.id),
});
export const countries = pgTable("countries", {
  id: serial('id').primaryKey(),
  name: varchar('name', {length: 256}).notNull(),
});

export const cities = pgTable('cities', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 256 }),
  countryId: integer('country_id').references(() => countries.id),
});
However, when I view the schema in Drizzle Studio, the following relation definitions appear in the 'Runner' section: 
export const citiesRelations = relations(cities, ({one}) => ({
  country: one(countries, {
    fields: [cities.countryId],
    references: [countries.id]
  }),
}));

export const countriesRelations = relations(countries, ({many}) => ({
  cities: many(cities),
}));
export const citiesRelations = relations(cities, ({one}) => ({
  country: one(countries, {
    fields: [cities.countryId],
    references: [countries.id]
  }),
}));

export const countriesRelations = relations(countries, ({many}) => ({
  cities: many(cities),
}));
My specific questions are: 1. Does the schema definition automatically infer and create the relationship for ORM operations when it contains .references(() => countries.id)? Or is it purely for generating database constraints (creating a FOREIGN KEY in SQL migrations)? 2. Is the relations code shown in Drizzle Studio just a development suggestion that I need to manually copy into my schema files , or is it automatically generated and used by the Drizzle ORM at runtime? 3. If I don't define the relations() functions manually, but only use references(), will queries such as db.query.countries.findMany(with: {cities: true}) work? My testing suggests that they do not, which makes me think that references() alone is insufficient for relation-based queries. 4. What is the precise division of responsibilities between: * .references() in table definitions * and relations() helper functions? * and Drizzle Studio's displayed relation suggestions?
3 Replies
hidoos
hidoosOP•5w ago
Despite reading the documentation, I could not find an explicit statement clarifying whether .references() automatically enables relation navigation in the Query API. Some sources suggest that these are completely separate systems, but I would like to confirm this.
⚡Z.E.U.S⚡
⚡Z.E.U.S⚡•5w ago
Hey @hidoos! 1. Drizzle Studio generates relations from database foreign keys and relations from the schema file(if exists). 2. This is only necessary for Drizzle runner to work and is not a suggestion. 3. Queries like db.query.countries.findMany(with: {cities: true}) want to work without relations(). 4. You can read about the differences here. If you have any other questions, feel free to ask.
hidoos
hidoosOP•5w ago
Thanks. I'll revisit the documentation.

Did you find this page helpful?