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.
drizzle
and migrate
imports depend on the database driver you're using
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",
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.
It introspects your database, detects changes and pushes them to remote/local database,
that even lets you have a no sql migration files
enviroment which gets popular nowadays.
$ drizzle-kit push:mysql ...
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