Getting Started
Database Drivers
Schema Integrations
Seed Generators
Utilities and Testing
The following files were used as context for generating this wiki page:
Type safety testing is a foundational component of the Drizzle ORM architecture, designed to ensure that the abstraction layer between TypeScript code and SQL databases remains strictly typed. By utilizing advanced TypeScript features such as conditional types, mapped types, and recursive type definitions, this subsystem validates that table definitions, query results, and complex SQL expressions are checked at compile time, eliminating a broad category of runtime errors associated with database schema drift or incorrect query construction.
The design relies on "test-type-level" validation, where the actual inferred types of ORM constructs are compared against expected structures using utility types. This provides immediate feedback to developers on whether changes to the core ORM logic break the contract between the database schema and the application's data models. It serves as a guardrail during the development of new features, ensuring that type inferencing for complex operations like multi-table joins or dynamic selections remains accurate and robust.
Beyond simple table definitions, this testing framework is critical for verifying how the ORM handles dialect-specific behaviors—such as MySQL's index locking algorithms, PostgreSQL-like array operations in Gel, or SQLite's view selection logic. By encoding database-specific behavior into the type system, the test suite acts as an automated documentation layer that forces the codebase to align with the specific constraints and features of each supported database dialect.
The core mechanism for type safety testing is the Expect utility. This utility is used to assert that the calculated type of an ORM construct matches an expected structure. These utilities are imported into every test file to verify that complex database query results or table definitions match the developer's intent at compile time.
The Expect utility validates type consistency. If the types do not match the target schema, the TypeScript compiler will throw an error, effectively failing the build. This mechanism turns the standard compilation process into a rigorous unit test for type definitions.
// Standard pattern for validating table column definitions
Expect<
Equal<
{
id: number;
name_db: string;
population: number | null;
},
InferSelectModel<typeof cities, { dbColumnNames: true }>
>
>;This component validates that the ORM accurately infers TypeScript interfaces from database table definitions. It is responsible for checking inferred models and insertion types against hard-coded expected structures, ensuring that optional columns, nullable fields, and default values are reflected correctly in the generated output.
These tests ensure that column attributes are translated accurately. For instance, when testing a serial column, the validation verifies whether the type is correctly inferred as number or number | null, accounting for whether the field is marked as required or optional in the database schema.
The query selection subsystem tests the complex type mapping that occurs when querying across multiple related tables. These tests exercise various builder methods to ensure that the resulting row object reflects the structure of the joined tables, correctly marking them as nullable when necessary (e.g., in a left join operation).
The complexity of these tests stems from the recursive nature of the result mapping, which must preserve table names and structures across deeply nested queries. By providing a full definition of the expected object structure, the tests confirm that the ORM correctly handles aliases and maintains key integrity during query construction.
Testing for SQL expressions involves validating the result types of raw SQL queries and operator expressions. This facet ensures that sql tagged templates correctly propagate type information. The tests verify the mapWith functionality, which allows developers to override default column typing, ensuring that complex database transformations are correctly cast back into TypeScript types.
A critical aspect of this testing is checking how operators interact with columns and subqueries, ensuring that valid SQL fragments are generated while maintaining type consistency between the input column and the operator's value arguments.
Different databases offer unique features (like MySQL's table indexing locking options or SingleStore's vector types), and the type testing subsystem treats these as distinct facets. This involves validating that specific methods—like index locking configurations—are only available on compatible objects.
The framework uses TypeScript's ts-expect-error to ensure that invalid combinations of database settings or methods are rejected by the compiler, creating a negative-testing path that guarantees API misuse is caught during the development of the ORM itself.
Tip
The use of @ts-expect-error is the standard way this subsystem verifies that disallowed operations are correctly restricted by the type system at compile time, providing a robust "negative testing" framework.
This component verifies the registration and configuration of custom database types. Custom types require a rigorous validation of their dataType, toDriver, and fromDriver functions to ensure that the interface remains consistent with the underlying database types.
The testing pattern involves declaring a customType with specific configuration objects and then asserting that the column result matches the expected internal representation of that column in the ORM's core.