Configuration files

Drizzle Kit lets you declare configurations in TypeScript, JavaScript or JSON configuration files.

You can have autocomplete experience and a very convenient environment variables flow!

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/schema.ts",
  out: "./drizzle",
} satisfies Config;

import type { Config } from "drizzle-kit";

/** @type { import("drizzle-kit").Config } */
export default {
  schema: "./src/schema.ts",
  out: "./drizzle",
};

{
  "schema": "./src/schema.ts",
  "out": "./drizzle",
}

Schema files paths

schema param lets you define where your schema file/files live.

You can have as many separate schema files as you want and define paths to them using glob or array of globs syntax.

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ ...
 │ ├ 📜 index.ts
 │ └ 📜 schema.ts 
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/schema.ts",
} satisfies Config;

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ 📂 user
 │ │ ├ 📜 handler.ts 
 │ │ └ 📜 schema.ts 
 │ ├ 📂 posts
 │ │ ├ 📜 handler.ts 
 │ │ └ 📜 schema.ts 
 │ └ 📜 index.ts
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/**/schema.ts",
  //or
  schema: ["./src/user/schema.ts", "./src/posts/schema.ts"]
} satisfies Config;

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ 📂 schema
 │ │ ├ 📜 user.ts 
 │ │ ├ 📜 post.ts 
 │ │ └ 📜 comment.ts 
 │ └ 📜 index.ts
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/schema/*",
} satisfies Config;

Migrations folder

out param lets you define folder for your migrations, it’s optional and drizzle by default.
It’s very useful since you can have many separate schemas for different databases in the same project and have different migration folders for them.

Migration folder contains .sql migration files and _meta folder which is used by drizzle-kit

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ ├ 📜 user.ts 
 │ ├ 📜 post.ts 
 │ └ 📜 comment.ts 
 ├ 📂 src
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/schema/*",
  out: "./drizzle",
} satisfies Config;

SQL breakpoints

breakpoints param lets you enable/disable SQL statement breakpoints in generated migrations.

It’s optional and true by default, it’s necessary to properly apply migrations on databases, that do not support multiple DDL alternation statements in one transaction (MySQL, SQLite) and Drizzle ORM has to apply them sequentially one by one.

CREATE TABLE `book` (
  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
  `name` text
);
--> statement-breakpoint
CREATE TABLE `book_to_author` (
  `author_id` integer,
  `book_id` integer,
  PRIMARY KEY(`book_id`, `author_id`)
);

Push and Pull

Drizzle Kit provides you introspect and push APIs.

We mirror connection params of database drivers.

import type { Config } from "drizzle-kit";

export default {
  schema: "./src/schema/*",
  out: "./drizzle",
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.DB_URL,
  }
} satisfies Config;

import type { Config } from "drizzle-kit";
import * as dotenv from "dotenv";
dotenv.config();

export default {
  schema: "./src/schema/*",
  out: "./drizzle",
  driver: 'pg',
  dbCredentials: {
    user: "postgres",
    password: process.env.DATABASE_PASSWORD,
    host: "127.0.0.1",
    port: 5432,
    database: "db",
  }
} satisfies Config;

Multi-project schema

tablesFilter param lets you filter tables with glob syntax for db push command. It’s useful when you have only one database available for several separate projects with separate sql schemas.

How to define multi-project tables with Drizzle ORM — see here.

import { serial, text, pgTableCreator } from 'drizzle-orm/pg-core';

const pgTable = pgTableCreator((name) => `project1_${name}`);

const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
});

import type { Config } from "drizzle-kit";
import * as dotenv from "dotenv";
dotenv.config();

export default {
  schema: "./src/schema/*",
  out: "./drizzle",
  driver: "mysql2",
  dbCredentials: {
    uri: process.env.DATABASE_URL,
  }
  tablesFilter: ["project1_*"],
} satisfies Config;

You can apply multiple or filters:

tablesFilter: ["project1_*", "project2_*"]