diff --git a/content/200-orm/300-prisma-migrate/050-getting-started.mdx b/content/200-orm/300-prisma-migrate/050-getting-started.mdx index d9fa3942c4..48e57429c3 100644 --- a/content/200-orm/300-prisma-migrate/050-getting-started.mdx +++ b/content/200-orm/300-prisma-migrate/050-getting-started.mdx @@ -6,12 +6,8 @@ sidebar_label: 'Getting started' tocDepth: 3 --- - - This page explains how to get started with migrating your schema in a development environment using Prisma Migrate. See [Developing with Prisma Migrate](/orm/prisma-migrate) for a more in-depth development workflow. - - ## Get started with Prisma Migrate from scratch To get started with Prisma Migrate in a development environment: @@ -161,7 +157,6 @@ The steps involved in **adding Prisma Migrate to your existing project** are: Make sure your Prisma schema is in sync with your database schema. This should already be true if you are using a previous version of Prisma Migrate. 1. Introspect the database to make sure that your Prisma schema is up-to-date: - ```terminal prisma db pull ``` @@ -170,48 +165,37 @@ Make sure your Prisma schema is in sync with your database schema. This should a Baselining is the process of initializing a migration history for a database that: -- ✔ Existed before you started using Prisma Migrate -- ✔ Contains data that must be maintained (like production), which means that the database cannot be reset +- Existed before you started using Prisma Migrate +- Contains data that must be maintained (like production), which means that the database cannot be reset Baselining tells Prisma Migrate to assume that one or more migrations have **already been applied**. This prevents generated migrations from failing when they try to create tables and fields that already exist. To create a baseline migration: 1. If you have a `prisma/migrations` folder, delete, move, rename, or archive this folder. - 1. Run the following command to create a `migrations` directory inside with your preferred name. This example will use `0_init` for the migration name: - - ```terminal - mkdir -p prisma/migrations/0_init - ``` - - - - The `0_` is important because Prisma Migrate applies migrations in a [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order). You can use a different value such as the current timestamp. - - - -1. Generate a migration and save it to a file using `prisma migrate diff` - - ```terminal no-lines - npx prisma migrate diff \ - --from-empty \ - --to-schema-datamodel prisma/schema.prisma \ - --script > prisma/migrations/0_init/migration.sql - ``` - -1. Review the generated migration + ```terminal + mkdir -p prisma/migrations/0_init + ``` + :::note + The `0_` is important because Prisma Migrate applies migrations in a [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order). You can use a different value such as the current timestamp. + :::: +1. Generate a migration and save it to a file using `prisma migrate diff`: + ```terminal no-lines + npx prisma migrate diff \ + --from-empty \ + --to-schema-datamodel prisma/schema.prisma \ + --script > prisma/migrations/0_init/migration.sql + ``` +1. Review the generated migration. ### Work around features not supported by Prisma Schema Language To include [unsupported database features](/orm/prisma-migrate/workflows/unsupported-database-features) that already exist in the database, you must replace or modify the initial migration SQL: 1. Open the `migration.sql` file generated in the [Create a baseline migration](#create-a-baseline-migration) section. - 1. Modify the generated SQL. For example: - - - If the changes are minor, you can append additional custom SQL to the generated migration - the following example creates a partial index: - + - If the changes are minor, you can append additional custom SQL to the generated migration. The following example creates a partial index: ```sql /* Generated migration SQL */ @@ -220,15 +204,11 @@ To include [unsupported database features](/orm/prisma-migrate/workflows/unsuppo WHERE success; --add-end ``` - - - If the changes are significant, it can be easier to replace the entire migration file with the result of a database dump ([`mysqldump`](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html), [`pg_dump`](https://www.postgresql.org/docs/12/app-pgdump.html)) - - - Note that the order of the tables matters when creating all of them at once, - since foreign keys are created at the same step. Therefore, either re-order - them or move constraint creation to the last step after all tables are - created, so you won't face `can't create constraint` errors - + - If the changes are significant, it can be easier to replace the entire migration file with the result of a database dump ([`mysqldump`](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html), [`pg_dump`](https://www.postgresql.org/docs/12/app-pgdump.html)). When using `pg_dump` for this, you'll need to updade the `search_path` as follows with this command: `SELECT pg_catalog.set_config('search_path', '', false);`; otherwise you'll run into the following error: `The underlying table for model '_prisma_migrations' does not exist.` +` + :::info + Note that the order of the tables matters when creating all of them at once, since foreign keys are created at the same step. Therefore, either re-order them or move constraint creation to the last step after all tables are created, so you won't face `can't create constraint` errors + ::: ### Apply the initial migrations