What Is a Database Migration? Why Your App Breaks After You Change the Database Schema.
Your app was working perfectly. You decided to add a new field to your database, or rename a column, or add a new table. You made the change and suddenly your…
Your app was working perfectly. You decided to add a new field to your database, or rename a column, or add a new table. You made the change and suddenly your app is throwing errors everywhere. Or you changed the database directly in your dashboard and now the app code no longer matches the database structure. This problem has a name: a schema mismatch. And the solution involves something called a database migration.
What a Database Schema Is
Your database has a structure: tables, columns, and the rules about what data each column can hold. This structure is called the schema.
Your app’s code is written based on this schema. If your code expects a column called email_address but the database has a column called email, the code fails. If your code tries to insert data into a column that does not exist yet, it fails. The code and the database need to match exactly.
A one-sentence definition: a database migration is a controlled change to your database schema that keeps your code and database in sync.
Why Changing the Database Directly Causes Problems
It is tempting to just go into Supabase or Firebase and add a column, rename something, or delete a table directly. Sometimes this works. Often it breaks things.
The problem is that your app’s code expects the old structure. When you change the database without updating the code, or update the code without changing the database, they fall out of sync. Errors appear because the app is trying to use a structure that no longer exists or trying to use a structure that does not exist yet.
This mismatch is the most common cause of the “it was working and I changed one thing and now it is broken” problem in database-backed apps.
The Right Way to Change Your Database Schema
Tell your AI what you want to change before changing anything. Do not go into your database dashboard and make changes directly. Instead, describe what you want to your AI:
“I want to add a phone_number field to my users table. It should be optional, store text, and allow null values. Can you write the database migration to add this field and update my app code to use it?”
Your AI will write both the database change and the corresponding code changes together, keeping everything in sync.
What Migrations Look Like
A migration is usually a SQL script or code that describes a specific change to the database schema:
sql
ALTER TABLE users ADD COLUMN phone_number TEXT;
Or in a migration framework:
python
def upgrade():
op.add_column('users', sa.Column('phone_number', sa.Text(), nullable=True))
Most database tools and frameworks have migration systems that track which migrations have been run and apply them in order. Ask your AI: “My app uses [describe your database setup]. How should I manage database migrations?”
How to Fix a Schema Mismatch That Has Already Happened
If you are already in a broken state because the database and code are out of sync:
- Do not make more changes. Stop and assess what is different.
- Check your error logs. The error message usually tells you exactly which column or table is missing or wrong.
- Ask your AI: “My app is throwing this error: [paste error]. I believe the database schema and my app code are out of sync. Can you help me identify what changed and how to bring them back into alignment?”
Your AI can read the error, identify the mismatch, and write the fix for either the database or the code depending on which one needs to change.
The One Thing to Remember
A database migration is a controlled, tracked change to your database structure. Changing the database directly without updating your code, or vice versa, causes schema mismatches that break your app. Always describe schema changes to your AI first and let it write the migration and code updates together. If you are already broken, paste the error to your AI and let it diagnose the mismatch.
Want your database-backed app running reliably in production? → Snapdock
New here? These might help: Why does my app lose all its data when I restart it? → I changed one thing and now my app is broken. How do I fix it? →