Overview
About Common Troubleshooting
When working with database schemas, migrations, and connectivity, you may occasionally run into issues such as snapshot collisions, out-of-date migration formats, connection configuration problems, or safety warnings during schema updates. This guide covers how to diagnose and resolve these common scenarios effectively.
Note
Always ensure your tooling is up-to-date before troubleshooting migration version mismatches.
Migration Conflicts and Outdated Snapshots
Conflict Types and Migration Formatting
Migration conflicts typically occur when multiple migration files point to the same parent snapshot, or when your project uses an older version of snapshot formats that need upgrading.
Outdated Migration Folders or Non-Latest Snapshots
If your migrations folder or individual snapshots are using an outdated version, you will see a notice indicating that snapshots are not of the latest version or that your folder format is legacy.
- Fix for legacy folders: Run
drizzle-kit up. - Fix for version upgrades: Depending on your dialect, run the appropriate update command to bring your snapshots up to the latest specification (such as upgrading PostgreSQL snapshots or migrating older V4/V5 snapshot schemas).
Snapshot Collisions
A snapshot collision happens when two or more distinct snapshot files point to the exact same parent snapshot ID.
- To check for collisions and malformed files in your migrations directory, run
drizzle-kit checkfor your specific database dialect. - If a collision is detected, review the generated report output to identify which child snapshots share the same parent path, and resolve the conflicting migration branches in your version control history.
Diagnosing Connection and Configuration Issues
Configuration and Connection Constraints
Connection issues often arise when required driver parameters are missing, or when using unsupported commands with specific database drivers.
Driver-Specific Restrictions and Missing Parameters
Certain drivers have strict limitations regarding which commands (migrate, push, pull, studio) they support. If you supply invalid parameters or use an unsupported command, the tool will report an error and list the required configuration parameters.
| Driver / Environment | Unsupported Commands | Required Parameters / Notes |
|---|---|---|
| Expo SQLite | migrate, studio, pull, push | Follow the specific Expo SQLite setup guide in the documentation. |
| SQLite Durable Objects | migrate, studio, pull, push | Not supported for these management commands. |
| D1 HTTP | Varies by context | Requires accountId, databaseId, and token. |
Warning
Attempting to run unsupported commands like drizzle-kit migrate or drizzle-kit studio with Expo SQLite or SQLite Durable Objects will terminate the process with an error message guiding you to the appropriate plugin or workflow.
Handling Data Loss Warnings and Safety Prompts
Understanding Safety Prompts
When pushing schema changes directly to a database, safety checks analyze pending statements to protect existing data (such as dropping tables, removing columns, or changing primary keys).
Common Warnings and Safeguards
- Dropping tables or columns: If you attempt to drop a table or column that contains existing rows, a warning displays the exact table or column name along with the item count.
- Not-null columns without defaults: Adding a
NOT_NULLcolumn to a table that already contains data without providing a default value will prompt a warning. Depending on the database engine, this may require truncating the table or aborting the operation. - Primary key alterations: Changing or dropping a primary key on a table with existing data can cause statements to fail or leave the table without a primary key.
- Auto-increment conflicts: In MySQL and SingleStore, removing a primary key from a table while leaving an
autoincrementproperty on a column will trigger an error because auto-increment columns must be defined as a key:Error:
There can be only one auto column, and it must be defined as a key. Make sure to remove autoincrement from your table.
Caution
Operations that truncate tables or drop populated columns will result in permanent data loss. Always back up your database before confirming destructive schema updates.
Related
On This Page
OverviewAbout Common TroubleshootingMigration Conflicts and Outdated SnapshotsConflict Types and Migration FormattingOutdated Migration Folders or Non-Latest SnapshotsSnapshot CollisionsDiagnosing Connection and Configuration IssuesConfiguration and Connection ConstraintsDriver-Specific Restrictions and Missing ParametersHandling Data Loss Warnings and Safety PromptsUnderstanding Safety PromptsCommon Warnings and SafeguardsRelated