Getting Started
Database Drivers
Schema Integrations
Seed Generators
Utilities and Testing
The following files were used as context for generating this wiki page:
Integration tests in this ecosystem serve as the primary validation layer for query builder correctness, type inference, and cross-dialect behavior. By exercising the Drizzle ORM against real-world query patterns, these tests ensure that the TypeScript type definitions align with the generated SQL.
The test suite is built on vitest and operates in a multi-dialect environment. It addresses the fundamental problem of ensuring that complex query compositions result in the correct TypeScript interface shapes, aligning with the underlying database engine's specifications.
At a mechanistic level, these tests use assertion utilities to perform static type checks against query results. This ensures that the Drizzle type engine correctly infers types across various query clauses. The integration suite is highly configurable, allowing for conditional execution of external database tests depending on the presence of environment configuration, which is controlled centrally by the vitest.config.ts file.
The integration test suite is orchestrated by a central vitest.config.ts file. This configuration manages the discovery, inclusion, and exclusion of test files across multiple database providers. It specifically implements a "skip-list" mechanism to filter out tests that require external network access or specific database instances when the environment variable SKIP_EXTERNAL_DB_TESTS is set.
The defineConfig utility is used to set global timeout limits for both hooks (hookTimeout) and test execution (testTimeout), and it explicitly forces sequential execution (singleThread: true) to avoid cross-pollination of state between tests that modify the same shared database schema.
Sources: integration-tests/vitest.config.ts:1-85
The core of the type-testing subsystem relies on static assertion utilities. This approach verifies that the TypeScript compiler's inferred type for a query result matches a manually defined, expected interface.
When a query builder statement is executed, the resulting type is compared against the expected shape. If the SQL query construction changes in a way that alters the resulting type, the assertion check fails at compile-time, providing immediate feedback.
Tip
Use static type assertions for every complex operation to ensure that nullability flags (e.g., | null) are propagated correctly.
Sources: drizzle-orm/type-tests/mysql/select.ts:47-55, drizzle-orm/type-tests/pg/select.ts:52-60
The tests define and validate the usage of dynamic query builders. These functions take a query builder instance as an argument and apply transformations.
The key mechanism here is the $dynamic() method, which allows for type-safe chaining even when the builder is passed through various helper functions. The tests ensure that after calling these helpers, the resultant promise resolves to the correctly mapped TypeScript type based on the initial query structure.
Sources: drizzle-orm/type-tests/mysql/select.ts:611-637