Drizzle Knowledge Patch

Drizzle ORM Knowledge Patch

Working method

Use this patch when changing Drizzle queries, schema-derived validation, or Drizzle Kit execution.

Before editing:

1. Identify the installed drizzle-orm and drizzle-kit versions.
2. Identify whether the CLI is launched by Node, Bun, or Deno.
3. Check whether the project imports drizzle-zod.
4. Search for dynamic values passed to sql.identifier() or sql.as().
5. Read the reference matching the task before choosing a migration.

Keep package versions distinct while reasoning:

• drizzle-orm controls query helpers and built-in Zod generators.
• drizzle-kit controls CLI module loading.
• zod remains a direct application dependency for generated schemas.

Do not infer one package's behavior from another package's version.

Reference index

Quick reference

Upgrade code that builds identifiers or aliases

Treat dynamic identifier and alias construction as security-sensitive.

Current releases properly escape values passed to:

• sql.identifier()
• sql.as()

Earlier releases could leave those values improperly escaped and expose applications to SQL injection.

Upgrade when either helper is used.

Then audit every call site that accepts a value originating outside the static query definition.

Read queries-and-runtime.md for the security boundary and review checklist.

Replace the deprecated drizzle-zod entry point

For drizzle-orm@1.0.0-beta.15 and newer, import schema generators from drizzle-orm/zod.

Install zod directly.

Do not expect new updates to the separate drizzle-zod package.

Use the built-in generators for all three supported schema purposes:

import {
  createInsertSchema,
  createSelectSchema,
  createUpdateSchema,
} from 'drizzle-orm/zod';

const selectUserSchema = createSelectSchema(users);
const insertUserSchema = createInsertSchema(users);
const updateUserSchema = createUpdateSchema(users);

Read schema-validation.md before changing dependencies or imports.

Match Drizzle Kit loading to the launch runtime

Starting with drizzle-kit@0.31.10, a Node launch uses the tsx loader instead of esbuild-register.

This lets the CLI load both ESM and CommonJS projects.

Bun and Deno launches do not use that Node loader path.

They use their native import systems instead.

Read migrations-and-kit.md before changing loader dependencies or debugging module format errors.

Query and SQL workflow

When a task touches dynamic SQL:

1. Search for sql.identifier( and .as( usages.
2. Determine whether values passed to them are static or dynamic.
3. Verify that the installed ORM contains the escaping correction.
4. Prefer upgrading over compensating for old helper behavior locally.
5. Review tests that exercise unusual identifier and alias values.
6. Treat a version upgrade as a security change in the handoff.

Do not claim that application-side validation replaces correct escaping.

Do not preserve an affected release merely because common values appear to work.

Use the exact helper names in review notes so the affected surface is easy to find.

Schema-validation workflow

When a project uses Drizzle-derived Zod schemas:

1. Confirm that the ORM supports the built-in Zod entry point.
2. Add zod as a direct dependency if it is not already direct.
3. Replace generator imports from drizzle-zod with drizzle-orm/zod.
4. Preserve calls to createSelectSchema().
5. Preserve calls to createInsertSchema().
6. Preserve calls to createUpdateSchema().
7. Remove drizzle-zod only after no imports still depend on it.
8. Run the project's type checks and validation tests.

Keep the migration narrow.

The entry-point change does not require renaming the three generator functions shown above.

Do not add a second compatibility wrapper unless the repository must support an older ORM that lacks the built-in entry point.

If old and new package support must coexist, state that constraint before selecting an import strategy.

Drizzle Kit workflow

When the CLI cannot load project configuration or source modules:

1. Record the actual launch runtime.
2. Record the installed drizzle-kit version.
3. For Node, reason about the tsx loader path.
4. For Bun, reason about Bun's native imports.
5. For Deno, reason about Deno's native imports.
6. Check whether a proposed fix belongs to the active runtime path.
7. Retest through the same runtime used by the project.

Do not prescribe esbuild-register for the current Node loading path.

Do not add tsx solely to control a Bun or Deno launch that bypasses it.

Distinguish a package-format problem from a launch-runtime mismatch in the final diagnosis.

Review checklist

Before completing a Drizzle change, verify the relevant items.

SQL security

• Confirm whether sql.identifier() is used.
• Confirm whether sql.as() is used.
• Confirm that affected code runs on a corrected ORM release.
• Call out the injection risk when an upgrade is required.

Zod integration

• Import generators from drizzle-orm/zod where supported.
• Keep zod as a direct dependency.
• Avoid introducing new reliance on drizzle-zod.
• Cover select, insert, and update generators used by the project.

CLI loading

• Identify Node, Bun, or Deno before changing loader configuration.
• Expect tsx, not esbuild-register, on the current Node path.
• Expect native imports on Bun and Deno paths.
• Reproduce and verify with the project's real launch command.

Handoff

State which package and runtime controlled the behavior you changed.

Mention any required minimum package version only where the code depends on that threshold.

For security-sensitive helper usage, explicitly recommend the corrected release rather than presenting the upgrade as optional cleanup.

For Zod migration work, report both the import change and the direct zod dependency.

For CLI work, report whether the tested path used Node's loader or a runtime-native import system.