import CodeTab from "@mdx/CodeTab.astro"; import CodeTabs from "@mdx/CodeTabs.astro"; import Section from "@mdx/Section.astro"; import Tab from "@mdx/Tab.astro"; import Tabs from "@mdx/Tabs.astro"; import Callout from "@mdx/Callout.astro"; import SchemaFilePaths from "@mdx/SchemaFilePaths.mdx" import Prerequisites from "@mdx/Prerequisites.astro" import Dialects from "@mdx/Dialects.mdx" import Drivers from "@mdx/Drivers.mdx" import DriversExamples from "@mdx/DriversExamples.mdx" import Npx from "@mdx/Npx.astro" # Drizzle Kit configuration file - Get started with Drizzle and `drizzle-kit` - [read here](/docs/get-started) - Drizzle schema fundamentals - [read here](/docs/sql-schema-declaration) - Database connection basics - [read here](/docs/connect-overview) - Drizzle migrations fundamentals - [read here](/docs/migrations) - Drizzle Kit [overview](/docs/kit-overview) and [config file](/docs/drizzle-config-file) Drizzle Kit lets you declare configuration options in `TypeScript` or `JavaScript` configuration files.

```plaintext {5} 📦 ├ ... ├ 📂 drizzle ├ 📂 src ├ 📜 drizzle.config.ts └ 📜 package.json ``` ```ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ dialect: "postgresql", schema: "./src/schema.ts", out: "./drizzle", }); ``` ```js import { defineConfig } from "drizzle-kit"; export default defineConfig({ dialect: "postgresql", schema: "./src/schema.ts", out: "./drizzle", }); ```

Example of an extended config file ```ts collapsable import { defineConfig } from "drizzle-kit"; export default defineConfig({ out: "./drizzle", dialect: "postgresql", schema: "./src/schema.ts", driver: "pglite", dbCredentials: { url: "./database/", }, extensionsFilters: ["postgis"], schemaFilter: "public", tablesFilter: "*", introspect: { casing: "camel", }, migrations: { prefix: "timestamp", table: "__drizzle_migrations__", schema: "public", }, entities: { roles: { provider: '', exclude: [], include: [] } }, breakpoints: true, strict: true, verbose: true, }); ``` ### Multiple configuration files You can have multiple config files in the project, it's very useful when you have multiple database stages or multiple databases or different databases on the same project: drizzle-kit generate --config=drizzle-dev.config.ts drizzle-kit generate --config=drizzle-prod.config.ts ```plaintext {5-6} 📦 ├ 📂 drizzle ├ 📂 src ├ 📜 .env ├ 📜 drizzle-dev.config.ts ├ 📜 drizzle-prod.config.ts ├ 📜 package.json └ 📜 tsconfig.json ``` ### 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`

```plaintext {3} 📦 ├ ... ├ 📂 drizzle │ ├ 📂 _meta │ ├ 📜 user.ts │ ├ 📜 post.ts │ └ 📜 comment.ts ├ 📂 src ├ 📜 drizzle.config.ts └ 📜 package.json ``` ```ts {5} import { defineConfig } from "drizzle-kit"; export default defineConfig({ dialect: "postgresql", // "mysql" | "sqlite" | "postgresql" | "turso" | "singlestore" schema: "./src/schema/*", out: "./drizzle", }); ```

## --- ### `dialect` Dialect of the database you're using | | | | :------------ | :----------------------------------- | | type | | | default | -- | | commands | `generate` `migrate` `push` `pull` `check` `up` | ```ts {4} import { defineConfig } from "drizzle-kit"; export default defineConfig({ dialect: "mysql", }); ``` ### `schema` [`glob`](https://www.digitalocean.com/community/tools/glob?comments=true&glob=/**/*.js&matches=false&tests=//%20This%20will%20match%20as%20it%20ends%20with%20'.js'&tests=/hello/world.js&tests=//%20This%20won't%20match!&tests=/test/some/globs) based path to drizzle schema file(s) or folder(s) contaning schema files. | | | | :------------ | :----------------- | | type | `string` `string[]` | | default | -- | | commands | `generate` `push` | ### `out` Defines output folder of your SQL migration files, json snapshots of your schema and `schema.ts` from `drizzle-kit pull` command. | | | | :------------ | :----------------- | | type | `string` `string[]` | | default | `drizzle` | | commands | `generate` `migrate` `push` `pull` `check` `up` | ```ts {4} import { defineConfig } from "drizzle-kit"; export default defineConfig({ out: "./drizzle", }); ``` ### `driver` Drizzle Kit automatically picks available database driver from your current project based on the provided `dialect`, yet some vendor specific databases require a different subset of connection params. `driver` option let's you explicitely pick those exceptions drivers. | | | | :------------ | :----------------- | | type | | | default | -- | | commands | `migrate` `push` `pull` | ## --- ### `dbCredentials` Database connection credentials in a form of `url`, `user:password@host:port/db` params or exceptions drivers() specific connection options. | | | | :------------ | :----------------- | | type | union of drivers connection options | | default | -- | | commands | `migrate` `push` `pull` |

```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "postgresql", dbCredentials: { url: "postgres://user:password@host:port/db", } }); ``` ```ts import { defineConfig } from 'drizzle-kit' // via connection params export default defineConfig({ dialect: "postgresql", dbCredentials: { host: "host", port: 5432, user: "user", password: "password", database: "dbname", ssl: true, // can be boolean | "require" | "allow" | "prefer" | "verify-full" | options from node:tls } }); ```

```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "mysql", dbCredentials: { url: "mysql://user:password@host:port/db", } }); ``` ```ts import { defineConfig } from 'drizzle-kit' // via connection params export default defineConfig({ dialect: "mysql", dbCredentials: { host: "host", port: 5432, user: "user", password: "password", database: "dbname", ssl: "...", // can be: string | SslOptions (ssl options from mysql2 package) } }); ```

```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "sqlite", dbCredentials: { url: ":memory:", // inmemory database // or url: "sqlite.db", // or url: "file:sqlite.db" // file: prefix is required by libsql } }); ``` ```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "turso", dbCredentials: { url: "libsql://acme.turso.io" // remote Turso database url authToken: "...", // or if you need local db url: ":memory:", // inmemory database // or url: "file:sqlite.db", // file: prefix is required by libsql } }); ``` ```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "sqlite", driver: "d1-http", dbCredentials: { accountId: "", databaseId: "", token: "", } }); ``` ```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "postgresql", driver: "aws-data-api", dbCredentials: { database: "database", resourceArn: "resourceArn", secretArn: "secretArn", }, }); ``` ```ts import { defineConfig } from 'drizzle-kit' export default defineConfig({ dialect: "postgresql", driver: "pglite", dbCredentials: { url: "./database/", // database folder path } }); ``` ### `migrations` When running `drizzle-kit migrate` - drizzle will records about successfully applied migrations in your database in log table named `__drizzle_migrations` in `public` schema(PostgreSQL only). `migrations` config options lets you change both migrations log `table` name and `schema`. | | | | :------------ | :----------------- | | type | `{ table: string, schema: string }` | | default | `{ table: "__drizzle_migrations", schema: "drizzle" }` | | commands | `migrate` | ```ts export default defineConfig({ dialect: "postgresql", schema: "./src/schema.ts", migrations: { table: 'my-migrations-table', // `__drizzle_migrations` by default schema: 'public', // used in PostgreSQL only, `drizzle` by default }, }); ``` ### `introspect` Configuration for `drizzle-kit pull` command. `casing` is responsible for in-code column keys casing | | | | :------------ | :----------------- | | type | `{ casing: "preserve" \| "camel" }` | | default | `{ casing: "camel" }` | | commands | `pull` |

```ts import * as p from "drizzle-orm/pg-core" export const users = p.pgTable("users", { id: p.serial(), firstName: p.text("first-name"), lastName: p.text("LastName"), email: p.text(), phoneNumber: p.text("phone_number"), }); ``` ```sql SELECT a.attname AS column_name, format_type(a.atttypid, a.atttypmod) as data_type FROM pg_catalog.pg_attribute a; ``` ``` column_name | data_type ---------------+------------------------ id | serial first-name | text LastName | text email | text phone_number | text ```

```ts import * as p from "drizzle-orm/pg-core" export const users = p.pgTable("users", { id: p.serial(), "first-name": p.text("first-name"), LastName: p.text("LastName"), email: p.text(), phone_number: p.text("phone_number"), }); ``` ```sql SELECT a.attname AS column_name, format_type(a.atttypid, a.atttypmod) as data_type FROM pg_catalog.pg_attribute a; ``` ``` column_name | data_type ---------------+------------------------ id | serial first-name | text LastName | text email | text phone_number | text ```

## --- ### `tablesFilter` If you want to run multiple projects with one database - check out [our guide](/docs/goodies#multi-project-schema). `drizzle-kit push` and `drizzle-kit pull` will by default manage all tables in `public` schema. You can configure list of tables, schemas and extensions via `tablesFilters`, `schemaFilter` and `extensionFilters` options. `tablesFilter` option lets you specify [`glob`](https://www.digitalocean.com/community/tools/glob?comments=true&glob=/**/*.js&matches=false&tests=//%20This%20will%20match%20as%20it%20ends%20with%20'.js'&tests=/hello/world.js&tests=//%20This%20won't%20match!&tests=/test/some/globs) based table names filter, e.g. `["users", "user_info"]` or `"user*"` | | | | :------------ | :----------------- | | type | `string` `string[]` | | default | -- | | commands | `generate` `push` `pull` | ```ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ dialect: "postgresql", tablesFilter: ["users", "posts", "project1_*"], }); ``` ### `schemaFilter` If you want to run multiple projects with one database - check out [our guide](/docs/goodies#multi-project-schema). `drizzle-kit push` and `drizzle-kit pull` will by default manage all tables in `public` schema. You can configure list of tables, schemas and extensions via `tablesFilters`, `schemaFilter` and `extensionFilters` options. `schemaFilter` option lets you specify list of schemas for Drizzle Kit to manage | | | | :------------ | :----------------- | | type | `string[]` | | default | `["public"]` | | commands | `push` `pull` | ```ts export default defineConfig({ dialect: "postgresql", schemaFilter: ["public", "schema1", "schema2"], }); ``` ### `extensionsFilters` Some extensions like [`postgis`](https://postgis.net/), when installed on the database, create its own tables in public schema. Those tables have to be ignored by `drizzle-kit push` or `drizzle-kit pull`. `extensionsFilters` option lets you declare list of installed extensions for drizzle kit to ignore their tables in the schema. | | | | :------------ | :----------------- | | type | `["postgis"]` | | default | `[]` | | commands | `push` `pull` | ```ts export default defineConfig({ dialect: "postgresql", extensionsFilters: ["postgis"], }); ``` ## --- ### `entities` This configuration is created to set up management settings for specific `entities` in the database. For now, it only includes `roles`, but eventually all database entities will migrate here, such as `tables`, `schemas`, `extensions`, `functions`, `triggers`, etc #### `roles` If you are using Drizzle Kit to manage your schema and especially the defined roles, there may be situations where you have some roles that are not defined in the Drizzle schema. In such cases, you may want Drizzle Kit to skip those `roles` without the need to write each role in your Drizzle schema and mark it with `.existing()`. The `roles` option lets you: - Enable or disable role management with Drizzle Kit. - Exclude specific roles from management by Drizzle Kit. - Include specific roles for management by Drizzle Kit. - Enable modes for providers like `Neon` and `Supabase`, which do not manage their specific roles. - Combine all the options above | | | | :------------ | :----------------- | | type | `boolean \| { provider: "neon" \| "supabase", include: string[], exclude: string[]}`| | default | `false` | | commands | `push` `pull` `generate` | By default, `drizzle-kit` won't manage roles for you, so you will need to enable that. in `drizzle.config.ts` ```ts export default defineConfig({ dialect: "postgresql", entities: { roles: true } }); ``` **You have a role `admin` and want to exclude it from the list of manageable roles** ```ts // drizzle.config.ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ ... entities: { roles: { exclude: ['admin'] } } }); ``` **You have a role `admin` and want to include to the list of manageable roles** ```ts // drizzle.config.ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ ... entities: { roles: { include: ['admin'] } } }); ``` **If you are using `Neon` and want to exclude roles defined by `Neon`, you can use the provider option** ```ts // drizzle.config.ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ ... entities: { roles: { provider: 'neon' } } }); ``` **If you are using `Supabase` and want to exclude roles defined by `Supabase`, you can use the provider option** ```ts // drizzle.config.ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ ... entities: { roles: { provider: 'supabase' } } }); ``` You may encounter situations where Drizzle is slightly outdated compared to new roles specified by database providers, so you may need to use both the `provider` option and `exclude` additional roles. You can easily do this with Drizzle: ```ts // drizzle.config.ts import { defineConfig } from "drizzle-kit"; export default defineConfig({ ... entities: { roles: { provider: 'supabase', exclude: ['new_supabase_role'] } } }); ``` ## --- ### `strict` Prompts confirmation to run printed SQL statements when running `drizzle-kit push` command. | | | | :------------ | :----------------- | | type | `boolean` | | default | `false` | | commands | `push` | ```ts export default defineConfig({ dialect: "postgresql", strict: false, }); ``` ### `verbose` Print all SQL statements during `drizzle-kit push` command. | | | | :------------ | :----------------- | | type | `boolean` | | default | `true` | | commands | `generate` `pull` | ```ts export default defineConfig({ dialect: "postgresql", verbose: false, }); ``` ### `breakpoints` Drizzle Kit will automatically embed `--> statement-breakpoint` into generated SQL migration files, that's necessary for databases that do not support multiple DDL alternation statements in one transaction(MySQL and SQLite). `breakpoints` option flag lets you switch it on and off | | | | :------------ | :----------------- | | type | `boolean` | | default | `true` | | commands | `generate` `pull` | ```ts export default defineConfig({ dialect: "postgresql", breakpoints: false, }); ```