This section documents version-specific API changes — prioritize recent major/minor releases.
-
Initialize Drizzle with your full schema object (or spread multiple schema files) when using relational queries to ensure all tables and relations are available. source
-
When using relational queries with PlanetScale, explicitly set the mode to 'planetscale' during Drizzle initialization due to its lack of lateral join support. source
-
For the Drizzle relational query API, ensure all table and relation definitions are provided during drizzle() initialization using the schema option. source
-
To change a generated column's expression in MySQL/PostgreSQL, you must drop the column, push the changes, and then re-add the column with the new expression. Drizzle-kit ignores direct modifications due to database-side complexities. source
-
For SQLite, changing a generated column's expression requires dropping and recreating the entire table, due to SQLite limitations. source
-
When using SELECT statements within an upsert clause, always include a WHERE clause, even if it's WHERE true, to avoid parsing ambiguities. source
-
Always define Drizzle Kit configurations in drizzle.config.ts to centralize settings for commands like push, generate, and migrate, enabling consistent and type-safe configurations. source
-
Always wrap your Drizzle Kit configuration object with defineConfig (imported from drizzle-kit) to enable type inference and ensure valid configuration options. source
-
Organize your Drizzle schema into multiple files (e.g., by feature or entity) and use a glob pattern (./src/schema/* or ./src/**/schema.ts) in the schema config option to allow for better modularity and maintainability. source
-
Use the out parameter in drizzle.config.ts to define a specific output folder for migration files, especially in projects with multiple database schemas, to maintain clear separation. source
-
Leverage multiple drizzle-kit configuration files (e.g., drizzle-dev.config.ts, drizzle-prod.config.ts) and specify them with --config flag when running commands, to manage different database stages or multiple databases within the same project. source
-
For vendor-specific databases like AWS Data API, PGLite, or Cloudflare D1, explicitly declare the driver in drizzle.config.ts even if Drizzle Kit attempts to auto-detect, to ensure correct connection parameters are used. source
-
Enable strict: true in your drizzle.config.ts for drizzle-kit push commands in production or shared environments. This prompts for confirmation before applying SQL changes, preventing accidental modifications. source
-
Utilize tablesFilter, schemaFilter, and extensionsFilters in drizzle.config.ts to precisely control which database entities Drizzle Kit manages, especially in multi-project, multi-schema, or multi-tenant environments. This helps avoid unintended modifications and ignores external/system tables. source
