Skip to content

Migration

Jump to bottom
Daniil Timofeev edited this page Aug 28, 2023 · 2 revisions

Introduction

What is a database migration?

A database migration is the process of changing the structure or content of a database in order to update, enhance, or adapt it to new requirements. Migration involves moving data, schema objects (such as tables, indexes, and views) from an existing database to a new or updated database as well. It allows developers to version and track changes to the database structure without breaking any part of the database.

Why do we need migrations?

Let’s go deeper into some actual benefits of a database migration:

  • Ease in development. As your application grows, the DB schema needs to be changed and updated accordingly. Database migration allows you to make changes to the schema without breaking the existing data or functionality.
  • Collaboration. In collaborative development teams, several developers might participate in a common task. Database migration offers an organized method for handling alterations to databases.
  • Deployment flexibility. DB migration allows you to deploy db changes along with the application code. This ensures that your db schema remains synchronized with the application code and is not broken by any piece of the code.
  • Cross-Platform Compatibility. Migrating a database can involve moving from one database management system to another. This ensures cross-platform compatibility and can be especially useful when transitioning from a proprietary system to an open-source solution.

How to perform a database migration?

  1. First and foremost, you should create a new branch with the name migration/name-of-migration.
$ git branch migration/name-of-migration
  1. Open prisma/schema.prisma. There is a defined data model. This model describes the structure of your database, including tables, fields, relationships, and constraints
  2. Make changes according to your task.
  3. Afterwards, you write this script:
    • dotenv -e .development.env - dotenv command is used to load environment variables from a specified file. In this case, the -e flag indicates that you're specifying the environment file, which is .development.env
    • npx prisma migrate dev - this part of the command tells Prisma that you want to perform a migration in development mode;
    • --name name_of_migration - this flag specifies the name of the migration;
    • --create-only - this flag instructs Prisma to only create the migration file and not apply the changes to the database. It's useful when you want to generate the migration file but want to manually apply the changes later.
$ dotenv -e .development.env -- npx prisma migrate dev --name name_of_migration --create-only

However, be careful. If Prisma warns you that data will be lost, migration is strictly prohibited.

  1. Open the prisma/migrations folder, your migration should be the last one. Open the migration folder and add the migration.sql file to Git.
  2. Check whether the project is built/everything works, get rid of mistakes.
  3. Commit all changes, make a pull request on dev.
  4. If changes are requested from your CR or QA, you should make the necessary adjustments (ONLY if changes are requested).
  5. NOTA BENE! You must write the script that initiates the process of creating and applying a migration in development mode only after your pull request has been approved:
$ npx prisma migrate dev

What are the risks associated with migration? How to avoid them?

  • Data Loss or Corruption. Incorrect migration scripts or processes can result in data loss or corruption, which can have severe consequences for your application and business. Avoidance: You should write npx prisma migrate dev only after your pull request has been approved. In addition, you must not change your SQL file after the script above.
  • Compatibility Issues. Migrating to a new database version or system might lead to compatibility issues with existing code or software. Avoidance: Research and understand the changes introduced in new versions before migrating.
  • Loss of Business Continuity. If migrations are not well-planned, they can disrupt business operations and lead to financial losses. Avoidance: Сreate detailed migration plans. Also communicate migration schedules to users and developers.
Clone this wiki locally