Zod Validation

Last updated Jul 2, 2026

Relevant source files

The following files were used as context for generating this wiki page:

Zod Validation provides a bridge between Drizzle ORM database definitions and Zod schemas, enabling automatic generation of validation logic from table and view definitions. By introspecting the Drizzle schema, this component generates Zod schemas that represent the structure of your database, ensuring type safety and input validation throughout the application lifecycle.

The system solves the problem of manual schema synchronization, where changes to the database structure would otherwise require tedious updates to validation layers. It provides specialized functions to create "select", "insert", and "update" schemas, which apply different rules regarding nullability and optionality based on the Drizzle column configuration.

Designed for tight integration with the Drizzle ecosystem, the subsystem leverages column metadata (such as data types, nullability, and default values) to construct the corresponding Zod types. This approach prevents runtime errors by ensuring that data interacting with the database adheres strictly to the defined schema at the application boundaries.

Core Transformation Logic

The transformation logic centers on mapping Drizzle column types to their equivalent Zod schema definitions. The columnToSchema function serves as the central dispatcher, inspecting column characteristics to decide the appropriate Zod validator.

It handles complex types by recursively calling itself for arrays or inspecting object-specific properties for types like points, lines, and geometry. The mechanism relies on isColumnType and isWithEnum to differentiate between standard and specialized column types, ensuring that even custom extensions are handled correctly.

Sources: drizzle-zod/src/column.ts:70-135

Schema Generation Pipeline

The generation of schemas (createSelectSchema, createInsertSchema, createUpdateSchema) is managed by handleColumns. This function iterates over a table's columns and applies conditional logic to ensure the schema matches the required database operation.

The pipeline processes each column by:

Checking if the column should be excluded via the conditions logic.
Converting the column to its base Zod schema.
Applying refinements if custom validation is provided by the user.
Applying nullability or optionality decorators based on column properties (e.g., notNull vs. default values).

Sources: drizzle-zod/src/schema.ts:19-64

Sources: drizzle-zod/src/schema.ts:15-64

Handling Conditions

The Conditions interface dictates how handleColumns modifies the schema for different database actions. These conditions are defined as sets of functions (never, optional, nullable) that act as guards.

Select: Makes columns nullable if !notNull.
Insert: Excludes generated columns, makes columns with defaults optional, and makes !notNull columns nullable.
Update: Excludes generated columns and treats all columns as optional.

Sources: drizzle-zod/src/schema.ts:76-92

Handling Numeric Types

Numeric and bigint column conversion includes built-in range validation. The numberColumnToSchema and bigintColumnToSchema functions extract constraints from Drizzle's internal metadata and apply Zod's gte() and lte() checks.

Note

The generation logic checks for unsigned SQL types to adjust the min value constraint automatically, ensuring generated schemas are as restrictive as the underlying database type.

Sources: drizzle-zod/src/column.ts:137-265

API Usage

Developers can use the high-level API to generate schemas directly from Drizzle table objects. The factory pattern allows for additional configuration, such as coercion of primitive types.

import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
 
const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  age: integer('age'),
});
 
const insertUserSchema = createInsertSchema(users);
const selectUserSchema = createSelectSchema(users);

Sources: drizzle-zod/src/schema.ts:94-119

Schema Factory

The createSchemaFactory provides a way to globally configure coercion behavior. When the factory is initialized with coerce: true, generated schemas will automatically add Zod's coercion layers for primitives, which is useful when dealing with form data or query parameters.

Sources: drizzle-zod/src/schema.ts:121-152