ArkType Validation

Last updated Jul 2, 2026

Relevant source files

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

ArkType Validation is a specialized integration layer within the Drizzle ecosystem designed to automatically generate high-performance runtime type validators from Drizzle database schema definitions. By leveraging the ArkType library, it bridges the gap between static database schema declarations and runtime data validation, ensuring that data fetched from or prepared for a database strictly conforms to the expected shapes.

This system resolves the common problem of "schema drift" between database columns and application types. Instead of manually maintaining separate validation schemas, developers can use Drizzle-defined tables and views as the single source of truth. The ArkType validation layer inspects Drizzle column metadata (type, length, constraints, and dialect-specific properties) to construct a corresponding Type object.

The architecture is built as an extensible adapter. The core engine traverses the Drizzle entity tree, identifies the underlying column types, and maps them to appropriate ArkType primitive or compound validators. This ensures that features like nullable columns, optional fields, and constraints (e.g., character limits or specific numeric ranges) are automatically enforced at the validation boundary.

Core Transformation Mechanism

The system relies on a central columnToSchema function that maps a Drizzle Column to an ArkType definition. This process involves a hierarchical type dispatch based on dataType and specific column implementation types.

Type Identification: The system uses isColumnType to perform runtime checks for specific database column classes (e.g., PgSmallInt, MySqlVarChar).
Data Mapping:
- For number types, the system performs range calculations based on CONSTANTS (e.g., INT16_MIN, INT8_UNSIGNED_MAX) to restrict the ArkType numeric range accordingly.
- For string types, it calculates maximum length requirements and applies pattern matching for specific types like UUIDs or binary vectors.
- For enum types, it checks isWithEnum and maps Drizzle enum values into an ArkType enumerated validator.

// Example: The dispatch logic in columnToSchema
export function columnToSchema(column: Column): Type {
    let schema!: Type;
    if (isWithEnum(column)) {
        schema = column.enumValues.length ? type.enumerated(...column.enumValues) : type.string;
    }
    // ... further type-specific checks
    if (column.dataType === 'number') {
        schema = numberColumnToSchema(column);
    }
    // ...
    return schema || type.unknown;
}

Sources: drizzle-arktype/src/column.ts:66-126

Numeric Constraint Enforcement

Numeric columns undergo a multi-stage validation transformation where the Drizzle column configuration is converted into a range-constrained ArkType validator. The mechanism reads the column type string to identify if it is "unsigned" and then selects a corresponding constant from CONSTANTS to define the bounds.

Database Type	Integer Constraint	Range Source
`TinyInt`	Yes	`CONSTANTS.INT8_MIN/MAX`
`SmallInt`	Yes	`CONSTANTS.INT16_MIN/MAX`
`Integer`	Yes	`CONSTANTS.INT32_MIN/MAX`
`Real/Double`	No	`CONSTANTS.INT48_MIN/MAX`

The mechanism uses a numberColumnToSchema function which applies .atLeast(min).atMost(max) to the resulting validator. If the column represents an integer type, the system additionally decorates the schema with type.keywords.number.integer.

Sources: drizzle-arktype/src/column.ts:128-229

Schema Traversal and Generation

The transformation from a Drizzle table to a full schema object occurs in schema.ts. The process follows a recursive pattern:

getColumns extracts the map of Drizzle columns from the table or view.
handleColumns iterates over this map, transforming each column into an ArkType validator.
If an object is found that isn't a column or SQL expression, the system treats it as a nested structure and recurses.

Note

During schema generation, if a refinement function is encountered, the generator treats it as an override, allowing users to extend the generated validator with custom logic while maintaining the underlying base schema.

Sources: drizzle-arktype/src/schema.ts:10-59

Handling Nullability and Optionality

The system dynamically adjusts the resulting Type validator based on the column's nullability and default settings:

Nullability: If conditions.nullable(column) returns true (e.g., column is notNull: false), the validator is updated using .or(type.null).
Optionality: If conditions.optional(column) returns true, the validator is wrapped using .optional().

This check happens post-refinement, ensuring that any user-provided constraints are wrapped correctly within the nullability or optionality logic.

Sources: drizzle-arktype/src/schema.ts:48-55

Worked Example: Validating a User Table

To use the system, define your Drizzle table and pass it to the createSelectSchema function.

import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core';
import { createSelectSchema } from 'drizzle-arktype';
 
const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  age: integer('age'),
});
 
// Generate validator
const userValidator = createSelectSchema(users);
 
// Validate data
const result = userValidator({ name: 'Alice', age: 30 });
 
if (result instanceof type.errors) {
  console.error('Validation failed', result);
} else {
  console.log('Validated user', result);
}

Sources: drizzle-arktype/src/schema.ts:61-74

Design Trade-offs

Design Choice	Benefit	Cost
Recursive Traversal	Supports nested objects and complex table structures	Increased complexity in handling circular references
Constraint-based Mapping	Automatically enforces database constraints at runtime	Tight coupling to Drizzle's internal column metadata structures
Refinement Injection	Allows custom user logic per field	Potentially leads to type-safety loss if misused in custom functions

Sources: drizzle-arktype/src/schema.ts:14-56