drizzle-team / drizzle-team/drizzle-orm

[DOCS]: Improve sqllite relation examples

Open Beginner friendly
#6,123 1 comment 0 reactions 0 assignees View on GitHub
docs
Dominant language
TypeScript
Stars
35.8k
Forks
1.6k
Avg merge
2d 7h
Merged PRs (30d)
4

Description

### Enhancement hasn't been filed before.

- [x] I have verified this enhancement I'm about to request hasn't been suggested before.

### Describe the enhancement you want to request

I've been using Drizzle for some time and completely overlooked the relations syntax and short notations to perform queries. It might be a me issue, but it might help to mention or reference it in the query/join docs.

These examples seem to be incorrect: https://orm.drizzle.team/docs/sqlite/relations

```
const relations = defineRelations({ users, posts }, (r) => ({
posts: {
author: r.one.users({
from: r.posts.ownerId,
to: r.users.id,
optional: false,
alias: 'custom_name',
where: {
verified: true,
}
}),
}
}))
```

Should be something like:
```
export const relations = relations(users, ({ one }) => ({
posts: one(posts, {
fields: [posts.ownerId],
references: [users.id],
}),
}));
```

I'm currently using a relation with a link table in between. Additional documentation for this structure would be appreciated. Here's an example from deepwiki that helped me figure out how to setup my config.

Many to Many
Here's the many-to-many example written for SQLite, using sqliteTable from drizzle-orm/sqlite-core.

1. Link table with SQLite schema

```
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
import { relations } from 'drizzle-orm';

const users = sqliteTable('users', {
id: integer('id').primaryKey(),
name: text('name'),
});

const chatGroups = sqliteTable('chat_groups', {
id: integer('id').primaryKey(),
name: text('name'),
});

const usersToChatGroups = sqliteTable('usersToChatGroups', {
userId: integer('user_id').notNull().references(() => users.id),
groupId: integer('group_id').notNull().references(() => chatGroups.id),
});
```

2. Add many()/one() relations config (same pattern as Postgres)

```
export const usersConfig = relations(users, ({ many }) => ({
usersToGroups: many(usersToChatGroups),
}));

export const chatGroupsConfig = relations(chatGroups, ({ many }) => ({
usersToGroups: many(usersToChatGroups),
}));

export const usersToChatGroupsConfig = relations(usersToChatGroups, ({ one }) => ({
group: one(chatGroups, { fields: [usersToChatGroups.groupId], references: [chatGroups.id] }),
user: one(users, { fields: [usersToChatGroups.userId], references: [users.id] }),
}));
```

3. Querying via db.query

```
const response = await db.query.users.findMany({
with: {
usersToGroups: {
columns: {},
with: { group: true },
},
},
});
```

Contributor guide

Open the contributing guide

Research direction

Start with the SQLite relations page at https://orm.drizzle.team/docs/sqlite/relations and compare its examples with the relations syntax shown in the issue. Update the incorrect examples and document the link-table many-to-many structure, including its relations configuration and db.query usage; done means the page accurately covers both patterns.

Written by the indexing model from the issue text.

Assessment

Tech stack
sqlite, typescript
Domain
databases, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
Half a day
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
75/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.