drizzle-team / drizzle-team/drizzle-orm
[BUG]: drizzle-kit migrate@0.31.0 Hangs After Reading Config on macOS (Node v20)
- Dominant language
- TypeScript
- Stars
- 35.8k
- Forks
- 1.6k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 4
Description
### Report hasn't been filed before.
- [x] I have verified that the bug I'm about to report hasn't been filed before.
### What version of `drizzle-orm` are you using?
0.43.0
### What version of `drizzle-kit` are you using?
0.31.0
### Other packages
_No response_
### Describe the Bug
When running the drizzle-kit migrate command (specifically version 0.31.0, the latest published on npm as of 2025-04-24), the process consistently hangs indefinitely after logging "Using 'pg' driver for database querying". It occurs before any apparent database interaction related to migrations (like checking or creating the __drizzle_migrations table or applying SQL). The hang happens even with freshly generated migration files after a database reset.
**Steps to Reproduce:**
Set up a project using Drizzle ORM with PostgreSQL.
Ensure package.json specifies "type": "module".
Install dependencies, specifically:
drizzle-kit@0.31.0
drizzle-orm@0.43.0
pg@8.15.5
Configure drizzle.config.ts with standard settings (schema path, out path, dialect: "postgresql", dbCredentials from process.env.DATABASE_URL).
Ensure .env file contains a valid DATABASE_URL for a running PostgreSQL database.
Generate at least one migration file using drizzle-kit generate (e.g., migrations/0000_....sql).
Run the migration command, for example: npx dotenv-cli -e .env -- npx drizzle-kit migrate --config=./drizzle.config.ts (or via npm run db:migrate).
**Expected Behavior:**
The drizzle-kit migrate command should:
Read the config.
Connect to the database.
Check for the __drizzle_migrations table (creating it if necessary).
Compare migration files in the migrations folder with records in the table.
Apply any pending migrations.
Report success or failure.
**Actual Behavior:**
The command outputs the following and then hangs indefinitely:
```
Reading config file '/path/to/your/drizzle.config.ts'
[drizzle.config.ts] DATABASE_URL: postgresql://user:********@host:port/db
Using 'pg' driver for database querying
(...hangs here...)
```
No further output is produced in the terminal. PostgreSQL logs (with log_statement = 'all' enabled) show no connection attempt from this specific migrate command process.
Environment:
OS: macOS (Apple Silicon, using Homebrew)
Node.js: v20.19.1 (LTS)
npm: 10.x (corresponding to Node v20)
drizzle-kit: 0.31.0
drizzle-orm: 0.43.0
pg: 8.15.5
Database: PostgreSQL v14 (via Homebrew)
**Relevant Configuration:**
```
package.json (devDependencies):
json
"devDependencies": {
// ... other devDependencies ...
"drizzle-kit": "^0.31.0",
"drizzle-orm": "^0.43.0",
// ...
},
```
drizzle.config.ts:
```
typescript
import { defineConfig } from "drizzle-kit";
if (!process.env.DATABASE_URL) {
throw new Error("DATABASE_URL environment variable is not set.");
}
export default defineConfig({
schema: "./shared/schema.ts", // Or your schema path
out: "./migrations",
dialect: "postgresql",
dbCredentials: {
url: process.env.DATABASE_URL,
},
verbose: true, // Tried with true/false
strict: true, // Tried with true/false
});
```
**Troubleshooting Steps Taken:**
Confirmed database connection works fine using psql with the exact same DATABASE_URL.
Confirmed Node.js pg driver connects and queries successfully using a minimal test script.
Confirmed drizzle-kit push command works correctly (connects, reads schema, reports no changes).
Switched from Node v23 (unstable) to v20 (LTS), including full rm -rf node_modules && rm package-lock.json && npm install.
Performed multiple clean installs.
Verified file permissions for migration files and folders.
Confirmed Node.js can read migration files using fs.readFile.
Isolated the hang:
It occurs only when .sql files are present in the migrations folder.
It occurs even if only the first CREATE TABLE statement from a migration file is present.
It occurs even after manually re-typing the SQL statement to rule out hidden characters.
Performed a "hard reset": Dropped all DB tables (including __drizzle_migrations), deleted the migrations folder, ran drizzle-kit generate to create a new initial migration file. The hang still occurred with drizzle-kit@0.31.0 when trying to run migrate on this fresh file.
Confirmed drizzle-kit@0.43.0 is not published on npm; 0.31.0 is the latest as of this report.
Downgrading to drizzle-kit@0.23.2 does not hang but shows an "outdated version" message, indicating the hang is specific to 0.31.0 (or versions between 0.23.2 and 0.31.0).
**Conclusion:**
The drizzle-kit migrate command in version 0.31.0 appears to have a bug causing it to hang during the initial file processing/parsing stage on macOS with Node v20, before attempting database operations. The issue is not related to database connectivity, credentials, file permissions, or the specific content of the SQL (as even freshly generated files trigger it), but seems tied to this specific version and environment combination.
Contributor guide
Assessment
This issue has not been assessed yet.