---
title: "Kit Overview"
description: "The \"Kit Overview\" encompasses the core logic responsible for database introspection, snapshot management, and the generation of migration SQL. Its primary role is to bridge the gap between applica..."
last_updated: "2026-07-02T09:35:18.588034+00:00"
canonical_url: "https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drizzle-kit/kit-overview"
---

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

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

- [drizzle-kit/src/snapshotsDiffer.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/snapshotsDiffer.ts)
- [drizzle-kit/src/introspect-pg.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-pg.ts)
- [drizzle-kit/src/cli/commands/migrate.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/cli/commands/migrate.ts)
</details>

The "Kit Overview" encompasses the core logic responsible for database introspection, snapshot management, and the generation of migration SQL. Its primary role is to bridge the gap between application-defined schemas and the actual state of a target database, facilitating the transition between declarative state definitions (snapshots) and imperative schema changes (migrations).

The system addresses the fundamental complexity of evolving database schemas, such as handling renames, moved objects, and attribute modifications that cannot be inferred from simple object comparisons alone. It leverages a "snapshot differ" architecture, where previous and current schema states are compared, and resolutions for ambiguities (like table or column renames) are provided via CLI prompts or automated resolvers.

At its architecture's center is a robust transformation pipeline: it converts schema differences into intermediate JSON-based statements, which are then serialized into vendor-specific SQL. This decoupling ensures that the logic for identifying changes is shared across databases (PostgreSQL, MySQL, SQLite, SingleStore), while the final SQL emission remains isolated in specific generators.

## Core Schema Differencing Mechanism

The core engine for detecting schema changes resides in `snapshotsDiffer.ts`. It performs a multi-stage comparison between `json1` (previous snapshot) and `json2` (current schema). The differ functions (`diffSchemasOrTables`, `diffColumns`, `diffPolicies`) compute the delta by identifying additions, deletions, and potential renames.

The system utilizes `copy()` to create working snapshots (`schemasPatchedSnap1`, `tablesPatchedSnap1`) that are progressively updated as renames are resolved. This allows the differ to operate on "patched" states where, for instance, a renamed table is treated as a single entity rather than a deletion and an addition.

> [!IMPORTANT]
> The differ does not assume names are immutable. It explicitly delegates rename/move resolution to injected resolver functions (e.g., `tablesResolver`), which can trigger user interaction or heuristics to map "deleted" objects to "created" objects.

Sources: [drizzle-kit/src/snapshotsDiffer.ts:603-1234](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/snapshotsDiffer.ts#L603-L1234)

## Snapshot Patching and State Normalization

To accurately reflect changes in the database, the differ must maintain consistency across nested object structures. When a schema or table is moved or renamed, the system performs a sequence of pointer updates:

1.  **Schema Normalization:** `schemaChangeFor` maps the current object to its new schema location based on rename resolution.
2.  **Enum and Sequence Tracking:** `enumsResolver` and `sequencesResolver` handle moving/renaming enums and sequences, which are then propagated through to dependent columns using `columnTypesChangeMap`.
3.  **Intermediate State:** As these resolutions are applied, `mapEntries` and `mapValues` are used to reconstruct the `tablesPatchedSnap1` state, which serves as the "corrected" baseline for the final `applyJsonDiff` call.

This state-patching flow ensures that by the time `applyJsonDiff` is invoked, the "old" snapshot and "new" snapshot are aligned by name and schema, leaving only additive, subtractive, or attribute-level changes to be computed.

Sources: [drizzle-kit/src/snapshotsDiffer.ts:614-709](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/snapshotsDiffer.ts#L614-L709)

## Statement Generation Pipeline

Once the final diff is calculated, the Kit converts these deltas into a unified format (`JsonStatement[]`). The pipeline follows a strict execution order to prevent dependency violations (e.g., dropping a table that is still referenced by a foreign key):

1.  **Drop Order:** Policies, indices, and check constraints are dropped first, followed by tables and columns.
2.  **Alteration:** Structural changes (e.g., `alter_table_alter_column_set_type`) are generated.
3.  **Creation:** Tables and columns are created; foreign keys and indices are then applied.

The system uses specific `prepare*` functions (e.g., `preparePgCreateTableJson`, `prepareAddColumns`) which return these `JsonStatement` objects.

```typescript
// Example: Simplified dependency-aware statement accumulation
jsonStatements.push(...jsonDropIndexesForAllAlteredTables);
jsonStatements.push(...jsonDeletedCompositePKs);
jsonStatements.push(...jsonTableAlternations);
jsonStatements.push(...jsonAddedCompositePKs);
jsonStatements.push(...jsonAddColumnsStatemets);
```

Sources: [drizzle-kit/src/snapshotsDiffer.ts:1973-2018](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/snapshotsDiffer.ts#L1973-L2018)

## PostgreSQL Introspection

Introspection, specifically for PostgreSQL, transforms database metadata into Drizzle-compatible TypeScript code. It handles complex PostgreSQL features such as:

- **Identity Columns:** Handled by `generateIdentityParams`, which differentiates between `generatedAlwaysAsIdentity` and `generatedByDefaultAsIdentity`.
- **Custom Types/Enums:** Uses `schema.enums` and `enumTypes` set to identify which types require `pgEnum` declarations.
- **Expression Defaults:** `mapColumnDefault` and `mapDefault` determine whether a default value is a literal or an SQL expression requiring `sql` template tags.

The system uses `withCasing` to translate database column names to their requested casing (camel vs. preserve).

> [!CAUTION]
> If a type fails to parse (e.g., an unknown geometry type), the generator will emit an `unknown()` call as a fallback to avoid crashing, which allows the developer to manually inspect the generated code.

Sources: [drizzle-kit/src/introspect-pg.ts:277-302](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-pg.ts#L277-L302), [drizzle-kit/src/introspect-pg.ts:1064-1101](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/introspect-pg.ts#L1064-L1101)

## Architecture Reference

The following diagram illustrates the interaction between snapshots, resolvers, and final SQL generation.

```mermaid
flowchart TD
    S1["Previous Snapshot"] --> Differ
    S2["Current Snapshot"] --> Differ
    Differ --> |"Resolvers<br>(Tables, Enums, Views)"| R[Resolvers]
    R --> |"Updates"| Differ
    Differ --> |"JSON Statements"| Gen["SQL Generator"]
    Gen --> |"Final Migration"| SQL["SQL Output"]
```

Sources: [drizzle-kit/src/snapshotsDiffer.ts:559-602](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/snapshotsDiffer.ts#L559-L602)

## Design Trade-offs Table

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **JSON Statement Intermediate Representation** | Allows cross-database logic for identifying changes; facilitates easy debugging and testing of diffs. | Adds an abstraction layer; requires serialization logic for every new database engine. |
| **Patcher-based Snapshot Alignment** | Simplifies complex diffs (renames/moves) by aligning state before the final comparison. | Increases memory usage; requires deep copies and iterative object mutations. |
| **Dependency-ordered Migration Pipeline** | Prevents runtime SQL errors by ensuring drops occur before creations/alterations. | Complex logic to maintain correct ordering as new constraint types are added to the system. |

Sources: [drizzle-kit/src/snapshotsDiffer.ts:1948-2022](https://github.com/blade47/drizzle-orm/blob/main/drizzle-kit/src/snapshotsDiffer.ts#L1948-L2022)

## Related

- [CLI Commands](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drizzle-kit/cli-commands)
- [Schema Serialization](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/drizzle-kit/schema-serialization)


## Sitemap

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