Get NextJet

Migrations

Learn how to modify your database schema and generate migrations.

In development and production, you will need to make changes to your database schema. This could be adding a new table, adding a new column, or changing the data type of a column.

We can use migrations to manage these changes. Migrations are a way to keep track of changes to your database schema over time. They allow you to make changes to your database in a controlled and repeatable way.

Before we get started, I recommend you understand and read about the database schema in the architecture section.

Create a Migration

When we make changes to our database schema we need to create a migration file. This file contains the SQL commands that will be executed to make the changes to the database.

To create a migration file, follow these steps:

Edit the Prisma Schema

Open the schema.prisma file in the packages/db/prisma directory.

Make the necessary changes to the schema. For example, if you want to add a new column to a table, you would add the column to the model in the schema.

You can learn more about the Prisma schema in the Prisma documentation.

Generate the migration

When you're happy with the changes you've made to the schema, you can generate the migration.

Run the following command in the root of the project to generate the migration:

pnpm db:migrate

Executing this command will generate a new migration file in the packages/db/prisma/migrations/ directory. This file includes SQL commands to implement the changes in the database.

The migration is automatically applied to the local database when you run the above command.

Sync the production database

If you're happy with the changes, you can apply the migration to the production database.

If you've completed the steps outlined in the deployment guide, you've already configured GitHub Actions to automatically apply migrations to the production database upon pushing changes to the main branch.

This is the recommended way to apply migrations to the production database. I highly discourage manually applying migrations to the production database.

Make sure to test the migration on your local database before applying it to production.

Prisma Commands

I have created some scripts to help you manage your database. You can find them in the package.json file in the root of the project.

Here are the scripts you can use to manage your database:

pnpm db:migrate

This command applies any pending migrations to your database during development. It's like telling Prisma to update your database with the changes you've made in your schema.

pnpm db:generate

This command generates Prisma client code based on your schema file. It creates TypeScript types that represent your database schema, making it easier to write type-safe code when working with your database.

pnpm db:push

This command applies local schema changes directly to the database without creating migration files.

pnpm db:deploy

This command deploys pending migrations to your database. It's similar to 'prisma migrate dev,' but it's specifically for deploying migrations in a production environment.

pnpm db:pull

This command pulls the database schema from the remote database and updates your local schema. It helps synchronize your local development environment with the schema in your production database.

pnpm db:seed

This command runs a custom script (packages/prisma/db/seed.ts) to populate your database with initial data. It's useful for setting up test data or initializing your database with default values.

pnpm db:reset

This command resets your database by dropping all tables and reapplying migrations from scratch. It's helpful for resetting your database to a clean state, typically during development or testing phases.

Last updated on