Drizzle Kit

Our most fundamental design principles of Drizzle ORM is to always stay explicit, provide opt-in solutions and never interfere. Our migrations toolkit is not an exception.

npm install -D drizzle-kit

Overview

Drizzle Kit - is a CLI companion for automatic SQL migrations generation and rapid prototyping

Conceptually it's very simple, you just declare Drizzle ORM TypeScript schema and you generate SQL migration from it. Then you can change that TypeScript schema and Drizzle Kit will generate you alternation migrations. That way you can have DDL source of truth in one type-safe place and under version control

Drizzle Kit lets you have your schema being split in multiple schema files and even have multiple schemas for different databases in one project
You can rapidly prototype database schema and push it directly to the database
And last but not least - you can pull schema from the existing database in the matter of seconds

Migration files

Migrations history is stored in .sql files in the migrations folder

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ ├ 📜 0000_premium_mister_fear.sql
 │ ├ 📜 0001_absurd_toad.sql
 │ ├ 📜 0002_adorable_human_torch.sql
 │ └ 📜 0003_boring_silver_sable.sql
 ├ ...
 ├ 📂 src
 ├ 📜 package.json
 └ ...

Each SQL migration file contains statements which you apply to the database through Drizzle ORM migration package or any other way suitable for your business case or personal preference

CREATE TABLE IF NOT EXISTS "user" (
  "id" serial,
  "name" text,
  "email" text,
  "password" text,
  "role" text,
  "created_at" timestamp,
  "updated_at" timestamp
);

Schema updates

Whenever you apply changes to the schema - you just rerun $ drizzle-kit generate... and it will generate SQL migration for you completely automatically in most of the cases

ALTER TABLE "user" ADD COLUMN "is_verified" boolean;

Running migrations

We're unopinionated on how you should run your migrations.
you can run them manually using SQL generated files, using external tools, etc. or use Drizzle ORM

We provide you a useful way to run generated migrations with migrate function which we implement for each driver and dialect specifically.
Drizzle will automatically keep track of applied migrations in your database.

import { drizzle } from "drizzle-orm/postgres-js";
import { migrate } from "drizzle-orm/postgres-js/migrator";
import postgres from "postgres";
 
const sql = postgres("...", { max: 1 })
const db = drizzle(sql);
 
await migrate(db, { migrationsFolder: "drizzle" });

Configuration

Drizzle Kit lets you declare configurations in TypeScript, JavaScript or JSON configuration files.
You can have autocomplete experience and very convenient enviroment variables flow!

import type { Config } from "drizzle-kit";
 
export default {
  schema: "./schema.ts",
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.DB_URL,
  }
} satisfies Config;

For list of all configuration params - see here

Prototyping with db push

Drizzle Kit lets you alter you database schema and rapidly move forward with a db push command.
That's very handy when you have remote databases like Neon, Planetscale or Turso.

Overview

If you want to iterate quickly during local development or if your project doesn't require migration files, drizzle offers a useful command called drizzle-kit push

When do you need to use the 'push' command?

1. During the prototyping and experimentation phase of your schema on a local environment.
2. When you are utilizing an external provider that manages migrations and schema changes for you (e.g., PlanetScale).
3. If you are comfortable modifying the database schema before your code changes can be deployed.

How it works?

When you run the command drizzle-kit push drizzle executes the following steps:

1. It retrieves your schema from the database and converts it to the "drizzle-schema" format.
2. The command reads all your schema files containing drizzle tables and converts them to the "drizzle-schema" format as well.
3. Drizzle then compares the two schemas and generates a set of statements that need to be executed against your database. These statements ensure that the database is synchronized with the schemas defined in your code.

$ drizzle-kit push:mysql
 
$ drizzle-kit push:sqlite

For extended push examples - see here

Introspecting with db pull

Drizzle Kit lets you pull DDL from existing database and prints you Drizzle TypeScript schema file completely automatically

$ drizzle-kit introspect:mysql ...

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ ├ 📜 0000_premium_mister_fear.sql
 │ └ 📜 schema.ts
 ├ ...
 ├ 📂 src
 ├ 📜 package.json
 └ ...

 export const user = pgTable("user", {
    id: serial("id"),
    name: text("name"),
    email: text("email"),
    password: text("password"),
    role: text("role").$type<"admin" | "customer">(),
    createdAt: timestamp("created_at"),
    updatedAt: timestamp("updated_at"),
  });

For extended introspect examples - see here

Drizzle Studio [NEW]

Drizzle Kit comes with bundled Drizzle Studio database browser and lets you launch it locally with one command.
Studio requires drizzle config file with schema and dbCredentials provided.

drizzle-kit studio
 
drizzle-kit studio --port 3000 ## custom port
drizzle-kit studio --verbose   ## log all sql statements