drizzle pages to show drizzle version

[SGP57]

I'm new to drizzle but have been struggling with it for a little while now.

The most confusing and time wasting aspect for me is the different versions. Not that you shouldn't have different versions but that your pages do not state which version they are for!

My current area of challenge is relations. Some pages show relations() and others show defineRelations(). Presumably you will know that this is the tip of the iceberg and there are inconsistencies however knowing which version would be a first step.

[sueun-dev]

The confusion is completely understandable — both syntaxes are valid, but they belong to different major versions of drizzle-orm.

relations() is the v1 API (drizzle-orm 0.x). It's still documented at orm.drizzle.team/docs/relations, but that page is now labeled "[OLD] Drizzle Relations".

defineRelations() is the v2 API, introduced in drizzle-orm 1.0.0-beta.1 (released November 2025). The new docs live at orm.drizzle.team/docs/relations-v2.

So which one to use depends on your installed version:

# Check your current version
cat node_modules/drizzle-orm/package.json | grep '"version"'

• If you're on 0.x (e.g., 0.36, 0.40), use relations()
• If you're on 1.0.0-beta.1 or newer, use defineRelations()

The v2 API is a real improvement over v1 — it supports native many-to-many via through, predefined filters on relations, and lets you define relations centrally for your entire schema rather than per-table. If you're starting fresh, it's worth jumping straight to v2 (npm install drizzle-orm@beta).

If you're already on v1 and want to migrate, the team has a step-by-step guide: orm.drizzle.team/docs/relations-v1-v2. Migration is designed to be incremental, not a big-bang rewrite.

The docs versioning isn't called out prominently enough, which is why this trips people up. Hopefully this clears it up!