---
title: "Quick Start"
description: "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 diver..."
last_updated: "2026-07-02T09:35:18.584674+00:00"
canonical_url: "https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/quick-start"
---

<details>
<summary>Relevant source files</summary>

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

- [drizzle-kit/src/cli/connections.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/cli/connections.ts)
- [drizzle-orm/src/singlestore/session.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore/session.ts)
- [drizzle-orm/type-tests/pg/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/type-tests/pg/select.ts)
- [drizzle-orm/src/xata-http/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/xata-http/driver.ts)
- [drizzle-orm/src/pg-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/dialect.ts)
- [drizzle-orm/src/pg-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-proxy/driver.ts)
- [drizzle-orm/src/singlestore-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore-proxy/driver.ts)
- [drizzle-orm/src/op-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/op-sqlite/driver.ts)
- [drizzle-orm/src/sqlite-proxy/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-proxy/driver.ts)
- [drizzle-orm/src/durable-sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/durable-sqlite/driver.ts)
- [drizzle-orm/src/sql-js/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sql-js/driver.ts)
- [drizzle-orm/src/prisma/sqlite/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/prisma/sqlite/driver.ts)
- [drizzle-orm/src/pglite/session.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pglite/session.ts)
- [drizzle-orm/src/prisma/pg/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/prisma/pg/driver.ts)
- [drizzle-orm/src/neon-http/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/neon-http/driver.ts)
- [drizzle-orm/src/aws-data-api/pg/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/aws-data-api/pg/driver.ts)
- [drizzle-orm/src/pglite/driver.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pglite/driver.ts)
</details>

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.

## Driver Initialization and Lifecycle

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.

- **Dialect instantiation**: `new PgDialect()`, `new SQLiteAsyncDialect()`, or `new SingleStoreDialect()` are initialized with optional `casing` configuration to ensure consistent column mapping.
- **Session creation**: Driver-specific classes (e.g., `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.
- **Dependency Verification**: Functions like `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](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/xata-http/driver.ts#L52-L91), [drizzle-orm/src/neon-http/driver.ts:124-169](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/neon-http/driver.ts#L124-L169), [drizzle-kit/src/cli/connections.ts:19](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/cli/connections.ts#L19)

## Connection Pooling and Management

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.

Sources: [drizzle-kit/src/cli/connections.ts:221-225](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/cli/connections.ts#L221-L225), [drizzle-orm/src/sqlite-proxy/driver.ts:30-40](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sqlite-proxy/driver.ts#L30-L40)

## Transactional Control Flow

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.

1. **Start Transaction**: A `BEGIN` command is executed via `tx.execute(sql\`begin\`)`.
2. **Execution**: The user-provided callback is executed against the transaction instance.
3. **Commit/Rollback**: The `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.

Sources: [drizzle-orm/src/singlestore/session.ts:277-317](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore/session.ts#L277-L317), [drizzle-kit/src/cli/connections.ts:976-981](https://github.com/blade47/drizzle-kit/src/cli/connections.ts#L976-L981)

## Architecture Overview (Class Diagram)

```mermaid
classDiagram
    class Database {
        <<Abstract>>
        +dialect: Dialect
        +session: Session
    }
    class Dialect {
        <<Abstract>>
    }
    class Driver {
        <<Interface>>
        +createSession()
    }
    Database *-- Dialect
```
Sources: [drizzle-orm/src/pg-core/db.ts:5](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pg-core/db.ts#L5), [drizzle-orm/src/xata-http/driver.ts:18-41](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/xata-http/driver.ts#L18-L41)

## Performance Considerations and Caching

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.

Sources: [drizzle-orm/src/singlestore/session.ts:13-14](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore/session.ts#L13-L14), [drizzle-orm/src/pglite/session.ts:90-92](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/pglite/session.ts#L90-L92)

## Execution Walkthrough: Querying

Tracing a query execution flow:
1. `PreparedQuery.execute()`: User calls query builder method.
2. `fillPlaceholders()`: Replaces template placeholders with real values.
3. `logger.logQuery()`: Records execution if logging is enabled.
4. `queryWithCache()`: Checks cache; if miss, triggers the driver's native execution method.
5. `client.query()`: The actual database client communicates with the server.
6. `mapResultRow()`: Transforms raw driver output into Drizzle-formatted objects.

Sources: [drizzle-orm/src/singlestore/session.ts:93-142](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/singlestore/session.ts#L93-L142)

## Runnable Example

This example demonstrates how to initialize a connection using the standard `drizzle()` factory with the `neon-http` driver.

```typescript
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);
```
Sources: [drizzle-orm/src/neon-http/driver.ts:171-226](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/neon-http/driver.ts#L171-L226)

## Related

- [Overview](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/getting-started/overview)
- [Database Drivers](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/database-drivers/database-drivers)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.