Getting Started
Database Drivers
Schema Integrations
Seed Generators
Utilities and Testing
The following files were used as context for generating this wiki page:
"TypeBox Validation" is a specialized bridge component within the Drizzle ecosystem designed to derive TypeBox schemas directly from Drizzle ORM column definitions. By leveraging the type metadata inherently present in Drizzle's database objects, this component automates the creation of validation logic, ensuring that TypeScript types and database-level constraints remain synchronized with runtime validation schemas.
The system solves the problem of "schema drift" between database definitions and application-level validation. Instead of manually maintaining separate validation schemas for input sanitization or serialization, developers can transform a Drizzle Column definition into a TypeBox TSchema using the columnToSchema function. This design decision prioritizes a single source of truth, where the database schema serves as the blueprint for both data access and validation.
Architecture-wise, it acts as a mapping layer that inspects the internal properties of Drizzle columns (such as dataType, enumValues, or specific vector dimensions) and maps them to corresponding TypeBox primitive or composite types. It serves as a foundational utility for Drizzle tools that require runtime validation, such as those generating API response bodies or verifying incoming payload integrity based on current table structure.
The core mechanism for translation is the columnToSchema function. It operates as a recursive dispatcher that identifies the underlying database column type using internal helper functions like isColumnType and isWithEnum.
isWithEnum). If true, it maps the enum values using mapEnumValues.PgGeometry or PgPointTuple are mapped to t.Tuple schemas of two numbers.PgHalfVector, PgVector) and Array types (PgArray) are processed to extract dimensions or sizes. If a dimension is present, the generated TypeBox schema is constrained using minItems and maxItems attributes to enforce strict structural adherence.Sources: drizzle-typebox/src/column.ts:71-114
Enum handling is a critical feature that links database string-based constraints to runtime validation. When the system detects a column with defined enum values, it executes mapEnumValues to create a key-value mapping suitable for TypeBox's enum validation, ensuring that only valid database-defined strings pass validation.
// Example of enum mapping logic
export function mapEnumValues(values: string[]) {
return Object.fromEntries(values.map((value) => [value, value]));
}Sources: drizzle-typebox/src/column.ts:67-69
Beyond simple column transformation, validation patterns are used in the broader Drizzle-Kit system to manage structural transitions. In drizzle-kit/src/snapshotsDiffer.ts, zod is utilized to enforce strict object structures—such as alteredTableScheme—which describe how columns, indices, and constraints change between two schema snapshots.
These definitions facilitate the transition from declarative schema definitions to actionable migration statements. By employing strict object schemas, the system ensures that the diffing logic maintains consistency when comparing table states across different database providers like PostgreSQL and MySQL.
Sources: drizzle-kit/src/snapshotsDiffer.ts:147-391
To handle non-primitive database types, the system implements custom type registrations in TypeBox. Notably, a custom Buffer type is registered to allow the validator to recognize binary data types common in SQL databases, which standard JSON schemas cannot represent naturally.
// Registering Buffer support for TypeBox
TypeRegistry.Set('Buffer', (_, value) => value instanceof Buffer);
export const bufferSchema: BufferSchema = { [Kind]: 'Buffer', type: 'buffer' } as any;Sources: drizzle-typebox/src/column.ts:64-65
The following diagram illustrates how the columnToSchema function resolves the final TypeBox schema.
Sources: drizzle-typebox/src/column.ts:71-120
Sources: drizzle-typebox/src/column.ts:71-120
Tip
Always verify that your column types are correctly imported into the drizzle-typebox module, as the system relies on specific isColumnType guards that check for the presence of the class name in the column's prototype chain.
Note
The columnToSchema function is designed for read-only reflection. It does not update the database state; it only generates the validation blueprint corresponding to the definition provided.