← All Posts

How to Do Prisma Schema Migration on Claude Code

To run a Prisma schema migration on Claude Code, open your project, describe the schema change you need, and ask Claude to update schema.prisma and run npx prisma migrate dev. Claude handles the migration file, applies it to your database, and regenerates the Prisma client in a single session. No context switching, no leaving your terminal.

  • Works with PostgreSQL, MySQL, SQLite, and SQL Server via Prisma's migrate dev command
  • Claude can scaffold new models, add relations, rename fields, and handle shadow database drift
  • Long migration sessions consume Claude Code usage tokens rapidly; hitting a limit mid-task means a 5-hour lockout

What is Prisma migrate and why use it with Claude Code?

Prisma Migrate is the schema-as-code migration tool built into Prisma ORM. You declare your data model in schema.prisma, and Prisma generates versioned SQL migration files that keep your database in sync with your code. Every migration is tracked in prisma/migrations, making rollbacks and team collaboration predictable.

Claude Code accelerates this workflow because writing schema changes, debugging migration conflicts, and regenerating seed files are all text-heavy, repetitive tasks that Claude handles well. Instead of consulting docs, you describe the goal ("add a nullable stripeCustomerId field to the User model") and let Claude produce the change, run the command, and fix any output errors in the same conversation.

How to set up Prisma in a Claude Code session

Before running migrations, confirm Prisma is installed and your database URL is configured. Tell Claude to verify the environment:

  1. Check that @prisma/client and prisma are in package.json
  2. Confirm DATABASE_URL is set in .env (and that .env is in .gitignore)
  3. Run npx prisma db pull if you're introspecting an existing database rather than starting fresh

Claude can scaffold the initial prisma/schema.prisma file for you if the project doesn't have one yet. Just tell it your database provider and the first models you need.

How to run a Prisma schema migration step by step

The standard migration loop in Claude Code looks like this:

1. Describe the schema change

Tell Claude exactly what you need: a new model, a new field, a relation change, or an index. Be specific. For example: "Add a Post model with id, title, content, published (Boolean, default false), and a many-to-one relation to User."

2. Let Claude edit schema.prisma

Claude will open prisma/schema.prisma and add or modify the relevant model block. It will respect existing conventions in your file (field naming, relation naming, enum usage).

3. Run migrate dev

Ask Claude to run the migration in dev mode:

npx prisma migrate dev --name add-post-model

This creates a timestamped migration file in prisma/migrations/, applies it to your local database, and regenerates @prisma/client. If there are shadow database conflicts or unapplied migrations, Claude will surface the error and propose a fix.

4. Regenerate the Prisma client

If you only edited the schema without migrating (for example, adding a comment or enum value), run:

npx prisma generate

Claude can also wire up the new types immediately in your application code during the same session.

5. Seed or verify data

For new models, ask Claude to update prisma/seed.ts and run npx prisma db seed to populate test data. This is especially useful when wrapping up a feature branch and you need the database in a known state before opening a PR.

For a deeper look at handling the raw SQL layer, see our guide on how to do PostgreSQL migrations on Claude Code and how to set up a Postgres database connection on Claude Code.

How to handle common Prisma migration errors in Claude Code

Drift detection errors

If your local database has manual changes not reflected in migration history, Prisma will report drift. Tell Claude to run npx prisma migrate diff to inspect the gap, then choose between resetting the database or baselining the current state with prisma migrate resolve.

Resetting the database in development

When you need a clean slate during active development, ask Claude to run:

npx prisma migrate reset

This drops the database, recreates it, runs all migrations, and optionally re-seeds data. Use it freely in local dev; never in production.

Deploying migrations to production

For staging and production environments, use npx prisma migrate deploy rather than migrate dev. The deploy command only applies pending migrations and never creates new ones or prompts interactively. Claude can add this command to your CI/CD pipeline or deployment script.

TypeScript type errors after schema changes

After adding fields, existing TypeScript code may fail to compile until @prisma/client is regenerated. Claude handles this automatically when running migrate dev, but if you're using a monorepo or custom output path, tell Claude to run prisma generate --schema=./path/to/schema.prisma explicitly. See also: handling TypeScript migrations on Claude Code.

How to add seed data after a Prisma migration

Seed files are often overlooked until you're setting up a fresh environment. Ask Claude to create or update prisma/seed.ts with realistic test data that matches your new schema. Then register the seed script in package.json:

"prisma": {
  "seed": "ts-node --compiler-options {\"module\":\"CommonJS\"} prisma/seed.ts"
}

Running npx prisma migrate reset will then automatically invoke the seed script. For a full walkthrough, see how to do data seeding on Claude Code.

Staying in flow: don't let usage limits interrupt a migration session

Prisma migration sessions are deceptively token-heavy. Editing schema files, running commands, reading error output, updating seed data, and fixing TypeScript types all consume Claude Code usage. A complex schema refactor can push you toward your 5-hour usage window limit right when you're wrapping up a PR.

That's the worst time to get locked out. Usagebar sits in your macOS menu bar and shows your Claude Code usage in real time. It sends smart alerts at 50%, 75%, and 90% of your limit so you can pace yourself, finish the migration, and avoid a mid-session cutoff. Your API credentials are stored securely in the macOS Keychain, and the tool is free for students with a pay-what-you-want model for everyone else.

You can also check your current usage directly in Claude Code with the /usage command or at claude.ai/settings/usage. For more on how usage resets and what counts toward your limit, see when does Claude Code usage reset.

Get Usagebar for instant download and flexible pricing.

Key takeaways

  1. Describe schema changes in plain language; Claude edits schema.prisma and runs migrate dev for you
  2. Use migrate dev locally, migrate deploy in CI/CD and production
  3. Reset drift with migrate reset (dev only) or migrate resolve for production baseline
  4. Always regenerate @prisma/client after schema changes to keep TypeScript types in sync
  5. Update prisma/seed.ts alongside migrations to keep your dev environment consistent
  6. Monitor your Claude Code usage with Usagebar so a long migration session doesn't end in a 5-hour lockout

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar