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.
Overview
Drizzle Kit — is a CLI companion for automatic SQL migrations generation and rapid prototyping.
Conceptually it’s very simple, you just declare a Drizzle ORM TypeScript schema and generate an SQL migration from it.
You can then change the original schema and Drizzle Kit will generate new migrations, that way you can have DDL source of truth in one type-safe place and under version control.
Drizzle Kit lets you split your schema in different 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.
Last but not least — you can pull the schema from an existing database in a matter of seconds ⚡️
Migration files
Migrations history is stored in .sql
files in the migrations folder
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.
You can also configure the prefixes for migrations, so they can be in a format that is compliant with the migration tool you are using or for your own convenience, for example Supabase would need 20240710095007_*.sql
format and drizzle has 0000_*.sql
be default
You can check all the prefix options here
You can use prefixes only if you don’t have any migration history already. The kit won’t work properly if you mix prefix formats within the same migration folder. Please ensure you use only one prefix format throughout the project.
We are working on making it possible to migrate from one prefix format to another and to ensure interoperability
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.
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 Kit or Drizzle ORM.
Using Drizzle Kit
You can use the native migrate CLI command drizzle-kit migrate
. It will gather all the needed information from the drizzle.config.ts
file to run migrations.
You can specify custom schema and migration table names in drizzle.config.ts
. For more information, please check the migrate documentation.
Using Drizzle ORM
We also 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.
Configuration
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!
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?
- During the prototyping and experimentation phase of your schema on a local environment.
- When you are utilizing an external provider that manages migrations and schema changes for you (e.g., PlanetScale).
- 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:
- It retrieves your schema from the database and converts it to the “drizzle-schema” format.
- The command reads all your schema files containing drizzle tables and converts them to the “drizzle-schema” format as well.
- 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.
For extended push
examples see here.
Introspecting with db pull
Drizzle Kit lets you pull DDL from existing database and prints a TypeScript schema file completely automatically.
For extended introspect
examples — see here.
Drizzle Studio
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.