drizzle-orm-best-practices

Drizzle ORM Best Practices

Treat Drizzle as a typed SQL builder over SQL dialect and driver contracts. Search its builders, operators, and helpers before writing sql. Keep data scope and invariants in SQL, read mutation metadata from the configured driver, let the database own persisted current time, and decode every unavoidable raw result at runtime.

Library Sources

• GitHub repository ID: drizzle-team/drizzle-orm
• Context7 library ID: /drizzle-team/drizzle-orm-docs
• DeepWiki repository ID: drizzle-team/drizzle-orm

Use Context7 for current documentation and DeepWiki when documentation is insufficient or conflicts with implementation.

Effective Strategies for Drizzle ORM

Read the linked guidance that governs the current task before writing or reviewing Drizzle code.

1. Keep SQL construction, data scope, and write contracts in the database boundary.
   • Before introducing any raw SQL, exhaust the built-in query builders and helpers so Drizzle keeps ownership of SQL generation, parameterization, and result decoding.
   • When a read exposes more data than its caller needs or checks access after retrieval, enforce query scope at the database boundary.
   • When behavior depends on whether a write changed zero, one, or many rows, interpret mutation cardinality from the driver result without returning row data solely to count it.
   • When several statements preserve one invariant, define a transaction boundary that passes the transaction through every participating helper.
   • When persisted timestamps mean the database's current time, use database-generated timestamps instead of an application clock.
2. Treat every raw result as untrusted at the ORM boundary.
   • When an unavoidable sql expression returns a value, apply runtime expression decoding and ban compile-time-only result annotations.
   • When a builder cannot represent a result-bearing operation, contain it behind complete raw-result validation rather than trusting a generic result type.