Getting Started
Database Drivers
Schema Integrations
Seed Generators
Utilities and Testing
The following files were used as context for generating this wiki page:
The "Quick Start" subsystem represents the entry-point factory layer for Drizzle ORM. Its primary purpose is to provide a unified, type-safe API for initializing database connections across a diverse ecosystem of SQL dialects and drivers. By abstracting the complexities of driver-specific configuration (such as connection pooling, dialect dialectics, and session management), it allows developers to interact with disparate databases through a consistent, ergonomic interface.
Architecturally, the component acts as a bridge between user configuration and underlying database driver implementation. It dynamically resolves dependencies—checking for required driver packages via checkPackage—and constructs the appropriate Database instances based on provided credentials or environment-specific configurations. This design ensures that initialization logic is decoupled from query logic, promoting maintainability and enabling support for complex scenarios like serverless environments, proxies, and edge-computing runtimes.
The subsystem adheres to a strict "constructor injection" pattern. Dialect objects and database wrappers are wired together at runtime to produce a Database instance that implements the standard Drizzle API surface. This mechanism allows the library to handle both local and remote execution paths, providing optimized paths for batching and transaction handling depending on the capabilities exposed by the target driver.
The initialization mechanism, typically exposed via a drizzle() function, follows a consistent sequence across all supported drivers. It instantiates a dialect, configures logging and caching, extracts table relational schemas (if provided), and finally creates the database instance.
new PgDialect(), new SQLiteAsyncDialect(), or new SingleStoreDialect() are initialized with optional casing configuration to ensure consistent column mapping.XataHttpDriver or PgliteDriver) act as factories, using createSession() to return internal session objects that contain the logic for executing SQL strings and handling result sets.checkPackage() are critical for runtimes that require optional drivers (e.g., pg, mysql2), throwing explicit errors or terminating the process if a mandatory package is missing from the environment.Sources: drizzle-orm/src/xata-http/driver.ts:52-91, drizzle-orm/src/neon-http/driver.ts:124-169, drizzle-kit/src/cli/connections.ts:19
In environment-agnostic drivers like mysql2 or node-postgres, the subsystem manages connection pooling by creating an instance of Pool. The drizzle function receives the configuration and instantiates the client, often with a max: 1 setting for Drizzle Kit specifically to prevent connection leakage.
When using proxy-based drivers (like sqlite-proxy or pg-proxy), the "pool" is replaced by a RemoteCallback that translates database requests into HTTP calls. This is a load-bearing abstraction: the callback captures the SQL and parameters, serializes them, and executes the request over the network.
Transactional support is implemented via the transaction() method on the resulting Database instances. The underlying session determines if it should utilize a pooled connection or a singleton.
BEGIN command is executed via tx.execute(sql\begin`)`.try...catch block wraps the transaction execution; if an error occurs, it triggers ROLLBACK and throws the error.Note
For non-transactional drivers like Cloudflare D1, transactionProxy maps the transaction request to a batch() call instead, as native BEGIN/COMMIT are not supported in that specific environment.
Caching is implemented as an optional configuration injected during the drizzle() call. The NoopCache is the default provider if no cache is provided, ensuring that standard execution incurs zero overhead from caching logic. When a custom cache is provided, the queryWithCache method checks existing keys before executing the database client's query() method.
Tip
Always provide a cache implementation when operating in high-latency network environments (e.g., edge runtimes) to avoid repeated SQL round-trips for idempotent read operations.
Tracing a query execution flow:
PreparedQuery.execute(): User calls query builder method.fillPlaceholders(): Replaces template placeholders with real values.logger.logQuery(): Records execution if logging is enabled.queryWithCache(): Checks cache; if miss, triggers the driver's native execution method.client.query(): The actual database client communicates with the server.mapResultRow(): Transforms raw driver output into Drizzle-formatted objects.This example demonstrates how to initialize a connection using the standard drizzle() factory with the neon-http driver.
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
// 1. Initialize client
const sql = neon(process.env.DATABASE_URL!);
// 2. Initialize DB instance
const db = drizzle(sql, {
logger: true,
casing: 'snake_case'
});
// 3. Perform a query
const result = await db.select().from(usersTable);