Getting Started
Configuration
Troubleshooting
Defining table relations allows you to establish how different tables in your database are connected to one another. By explicitly linking these tables, you can easily query data across related entities—for example, retrieving a specific user along with all of their associated posts.
In our system, relations are defined using two primary helper functions:
one: Defines a one-to-one relationship. Use this when a record in your source table is associated with a single record in another table (e.g., one user has one profile).many: Defines a one-to-many relationship. Use this when a record in your source table is associated with multiple records in another table (e.g., one user has many posts).You can define these relationships using the relations function. This function takes your source table and a configuration block where you define how it relates to other tables.
export const usersRelations = relations(users, ({ many, one }) => ({
posts: many(posts),
profile: one(profiles),
}));Tip
If you have multiple relationships between the same two tables, ensure you provide a unique relationName for each to avoid ambiguity during data retrieval.
Warning
While relations make queries simpler, defining complex circular dependencies can sometimes lead to unexpected behavior. Keep your relationship structure as flat and logical as possible.
The following diagram illustrates how the system processes your relation definitions:
When defining a one relationship, you can explicitly map specific columns if the relationship does not follow standard naming conventions. By providing the fields (from the source table) and references (from the target table), you maintain full control over how data is joined.
Note
In most cases, the system can automatically infer these links. Only provide explicit column mappings if your database structure requires specific, non-standard key linking.