AgentSkillsCN

drizzle-best-practices

针对使用 PostgreSQL 的 TypeScript 项目，提供 Drizzle ORM 最佳实践。适用于编写、审查或优化 Drizzle ORM 的 Schema、查询、关联、迁移，以及面向 Postgres 的数据库配置时使用。每当您看到 drizzle-orm 导入语句、pgTable 定义、drizzle-kit 配置文件，或关系型查询模式时，均可参考并应用这些最佳实践。此外，在使用 Drizzle + Postgres 新建项目、从其他 ORM 迁移，或排查 Drizzle Schema 中的类型错误时，亦可灵活运用这些指南。

SKILL.md
--- frontmatter
name: drizzle-best-practices
description: >
  Drizzle ORM best practices for TypeScript projects using PostgreSQL. Use this skill when
  writing, reviewing, or optimizing Drizzle ORM schemas, queries, relations, migrations, or
  database configurations targeting Postgres. Apply these guidelines whenever you see
  drizzle-orm imports, pgTable definitions, drizzle-kit config files, or relational query
  patterns. Also use when setting up a new project with Drizzle + Postgres, migrating from
  another ORM, or troubleshooting type errors in Drizzle schemas.
license: MIT
compatibility: TypeScript projects using Node.js or edge runtimes with drizzle-orm and a PostgreSQL database.
metadata:
  author: Marc A. Maceira Zayas
  abstract: >
    Comprehensive Drizzle ORM best practices guide for TypeScript developers building on
    PostgreSQL. Contains guidance across 8 categories from critical (schema design, query
    patterns) to incremental (advanced features). Each reference includes explanations,
    correct vs incorrect code examples, and rationale for why the pattern matters.
    Engine-specific Postgres patterns (identity columns, JSONB, arrays, enums, etc.) are
    documented in a dedicated reference file to keep the skill modular.

Drizzle ORM Best Practices (PostgreSQL)

Comprehensive best practices guide for Drizzle ORM with PostgreSQL. Contains guidance across 8 categories, prioritized by impact to help you write correct, performant, and maintainable database code.

When to Apply

Reference these guidelines when:

  • •Defining table schemas with pgTable
  • •Writing select, insert, update, or delete queries
  • •Setting up relations between tables using defineRelations or the legacy relations API
  • •Configuring drizzle-kit for migrations (generate, push, pull)
  • •Inferring TypeScript types from your schema
  • •Choosing between the SQL-like API and the relational query API
  • •Optimizing query performance with prepared statements or batch operations
  • •Integrating Drizzle with serverless Postgres providers (Neon, Supabase, etc.)

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Schema DesignCRITICALschema-
2Query PatternsCRITICALquery-
3RelationsHIGHrelations-
4MigrationsHIGHmigrations-
5Type SafetyMEDIUM-HIGHtypes-
6PerformanceMEDIUMperf-
7Database DriversMEDIUMdriver-
8Advanced PatternsLOWadvanced-

How to Use

Read individual reference files for detailed explanations and code examples:

code
references/engine-postgres.md          # Postgres-specific types, features, and patterns
references/schema-table-definitions.md
references/query-select-patterns.md
references/relations-defining.md
references/_sections.md                # Full index of all references

Each reference file contains:

  • •Brief explanation of why it matters
  • •Incorrect code example with explanation
  • •Correct code example with explanation
  • •Links to official Drizzle documentation

References