From acf729346e21432b160bd1e84c1b059c250a1956 Mon Sep 17 00:00:00 2001 From: Vrut Thumar <104627643+vrutthumar@users.noreply.github.com> Date: Mon, 26 Feb 2024 14:43:34 +0530 Subject: [PATCH] Update migrations.md I have corrected some of the grammatical errors. --- .../version-6.x.x/other-topics/migrations.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/versioned_docs/version-6.x.x/other-topics/migrations.md b/versioned_docs/version-6.x.x/other-topics/migrations.md index f5163d53a..f782c0592 100644 --- a/versioned_docs/version-6.x.x/other-topics/migrations.md +++ b/versioned_docs/version-6.x.x/other-topics/migrations.md @@ -2,11 +2,11 @@ title: Migrations --- -Just like you use [version control](https://en.wikipedia.org/wiki/Version_control) systems such as [Git](https://en.wikipedia.org/wiki/Git) to manage changes in your source code, you can use **migrations** to keep track of changes to the database. With migrations you can transfer your existing database into another state and vice versa: Those state transitions are saved in migration files, which describe how to get to the new state and how to revert the changes in order to get back to the old state. +Just like you use [version control](https://en.wikipedia.org/wiki/Version_control) systems such as [Git](https://en.wikipedia.org/wiki/Git) to manage changes in your source code, you can use **migrations** to keep track of changes to the database. With migrations, you can transfer your existing database into another state and vice versa: Those state transitions are saved in migration files, which describe how to get to the new state and how to revert the changes in order to get back to the old state. You will need the [Sequelize Command-Line Interface (CLI)](https://github.com/sequelize/cli). The CLI ships support for migrations and project bootstrapping. -A Migration in Sequelize is a javascript file which exports two functions, `up` and `down`, that dictates how to perform the migration and undo it. You define those functions manually, but you don't call them manually; they will be called automatically by the CLI. In these functions, you should simply perform whatever queries you need, with the help of `sequelize.query` and whichever other methods Sequelize provides to you. There is no extra magic beyond that. +A Migration in Sequelize is a javascript file that exports two functions, `up` and `down`, that dictate how to perform the migration and undo it. You define those functions manually, but you don't call them manually; they will be called automatically by the CLI. In these functions, you should simply perform whatever queries you need, with the help of `sequelize.query` and whichever other methods Sequelize provides to you. There is no extra magic beyond that. ## Installing the CLI @@ -28,14 +28,14 @@ npx sequelize-cli init This will create following folders -- `config`, contains config file, which tells CLI how to connect with database +- `config`, contains the config file, which tells CLI how to connect with the database - `models`, contains all models for your project - `migrations`, contains all migration files - `seeders`, contains all seed files ### Configuration -Before continuing further we will need to tell the CLI how to connect to the database. To do that let's open default config file `config/config.json`. It looks something like this: +Before continuing further, we must tell the CLI how to connect to the database. To do that let's open the default config file `config/config.json`. It looks something like this: ```json { @@ -63,17 +63,17 @@ Before continuing further we will need to tell the CLI how to connect to the dat } ``` -Note that the Sequelize CLI assumes mysql by default. If you're using another dialect, you need to change the content of the `"dialect"` option. +Note that the Sequelize CLI assumes MySQL by default. If you're using another dialect, you need to change the content of the `"dialect"` option. Now edit this file and set correct database credentials and dialect. The keys of the objects (e.g. "development") are used on `model/index.js` for matching `process.env.NODE_ENV` (When undefined, "development" is a default value). -Sequelize will use the default connection port for each dialect (for example, for postgres, it is port 5432). If you need to specify a different port, use the `"port"` field (it is not present by default in `config/config.js` but you can simply add it). +Sequelize will use the default connection port for each dialect (for example, for Postgres, it is port 5432). If you need to specify a different port, use the `"port"` field (it is not present by default in `config/config.js` but you can simply add it). -**Note:** _If your database doesn't exist yet, you can just call `db:create` command. With proper access it will create that database for you._ +**Note:** _If your database doesn't exist yet, you can just call `db:create` command. With proper access, it will create that database for you._ ## Creating the first Model (and Migration) -Once you have properly configured CLI config file you are ready to create your first migration. It's as simple as executing a simple command. +Once you have properly configured the CLI config file you are ready to create your first migration. It's as simple as executing a simple command. We will use `model:generate` command. This command requires two options: @@ -89,9 +89,9 @@ npx sequelize-cli model:generate --name User --attributes firstName:string,lastN This will: - Create a model file `user` in `models` folder; -- Create a migration file with name like `XXXXXXXXXXXXXX-create-user.js` in `migrations` folder. +- Create a migration file with a name like `XXXXXXXXXXXXXX-create-user.js` in the `migrations` folder. -**Note:** _Sequelize will only use Model files, it's the table representation. On the other hand, the migration file is a change in that model or more specifically that table, used by CLI. Treat migrations like a commit or a log for some change in database._ +**Note:** _Sequelize will only use Model files, it's the table representation. On the other hand, the migration file is a change in that model or more specifically that table, used by CLI. Treat migrations like a commit or a log for some change in the database._ ## Running Migrations @@ -103,13 +103,13 @@ npx sequelize-cli db:migrate This command will execute these steps: -- Will ensure a table called `SequelizeMeta` in database. This table is used to record which migrations have run on the current database -- Start looking for any migration files which haven't run yet. This is possible by checking `SequelizeMeta` table. In this case it will run `XXXXXXXXXXXXXX-create-user.js` migration, which we created in last step. +- Will ensure a table called `SequelizeMeta` in the database. This table is used to record which migrations have run on the current database +- Start looking for any migration files that haven't run yet. This is possible by checking the `SequelizeMeta` table. In this case, it will run the `XXXXXXXXXXXXXX-create-user.js` migration, which we created in the last step. - Creates a table called `Users` with all columns as specified in its migration file. ## Undoing Migrations -Now our table has been created and saved in the database. With migration you can revert to old state by just running a command. +Now our table has been created and saved in the database. With migration, you can revert to the old state by just running a command. You can use `db:migrate:undo`, this command will revert the most recent migration. @@ -117,7 +117,7 @@ You can use `db:migrate:undo`, this command will revert the most recent migratio npx sequelize-cli db:migrate:undo ``` -You can revert back to the initial state by undoing all migrations with the `db:migrate:undo:all` command. You can also revert back to a specific migration by passing its name with the `--to` option. +You can revert to the initial state by undoing all migrations with the `db:migrate:undo:all` command. You can also revert to a specific migration by passing its name with the `--to` option. ```text npx sequelize-cli db:migrate:undo:all --to XXXXXXXXXXXXXX-create-posts.js @@ -127,17 +127,17 @@ npx sequelize-cli db:migrate:undo:all --to XXXXXXXXXXXXXX-create-posts.js Suppose we want to insert some data into a few tables by default. If we follow up on the previous example we can consider creating a demo user for the `User` table. -To manage all data migrations you can use seeders. Seed files are some change in data that can be used to populate database tables with sample or test data. +To manage all data migrations you can use seeders. Seed files are some changes in data that can be used to populate database tables with sample or test data. -Let's create a seed file which will add a demo user to our `User` table. +Let's create a seed file that will add a demo user to our `User` table. ```text npx sequelize-cli seed:generate --name demo-user ``` -This command will create a seed file in `seeders` folder. File name will look something like `XXXXXXXXXXXXXX-demo-user.js`. It follows the same `up / down` semantics as the migration files. +This command will create a seed file in the `seeders` folder. The file name will look something like `XXXXXXXXXXXXXX-demo-user.js`. It follows the same `up / down` semantics as the migration files. -Now we should edit this file to insert demo user to `User` table. +Now we should edit this file to insert the demo user to the `User` table. ```js module.exports = { @@ -158,7 +158,7 @@ module.exports = { ## Running Seeds -In last step you created a seed file; however, it has not been committed to the database. To do that we run a simple command. +In the last step you created a seed file; however, it has not been committed to the database. To do that we run a simple command. ```text npx sequelize-cli db:seed:all @@ -211,7 +211,7 @@ We can generate this file using `migration:generate`. This will create `xxx-migr npx sequelize-cli migration:generate --name migration-skeleton ``` -The passed `queryInterface` object can be used to modify the database. The `Sequelize` object stores the available data types such as `STRING` or `INTEGER`. Function `up` or `down` should return a `Promise`. Let's look at an example: +The passed `queryInterface` object can be used to modify the database. The `Sequelize` object stores the available data types such as `STRING` or `INTEGER`. The function `up` or `down` should return a `Promise`. Let's look at an example: ```js module.exports = { @@ -231,7 +231,7 @@ module.exports = { }; ``` -The following is an example of a migration that performs two changes in the database, using an automatically-managed transaction to ensure that all instructions are successfully executed or rolled back in case of failure: +The following is an example of a migration that performs two changes in the database, using an automatically managed transaction to ensure that all instructions are successfully executed or rolled back in case of failure: ```js module.exports = { @@ -289,7 +289,7 @@ module.exports = { } ``` -The next example is of a migration that uses async/await where you create an unique index on a new column, with a manually-managed transaction: +The next example is of a migration that uses async/awaits where you create a unique index on a new column, with a manually-managed transaction: ```js module.exports = { @@ -332,7 +332,7 @@ module.exports = { }; ``` -The next example is of a migration that creates an unique index composed of multiple fields with a condition, which allows a relation to exist multiple times but only one can satisfy the condition: +The next example is of a migration that creates a unique index composed of multiple fields with a condition, which allows a relation to exist multiple times but only one can satisfy the condition: ```js module.exports = { @@ -375,7 +375,7 @@ This is a special configuration file. It lets you specify the following options Some scenarios where you can use it: -- You want to override default path to `migrations`, `models`, `seeders` or `config` folder. +- You want to override the default path to the `migrations`, `models`, `seeders`, or `config` folder. - You want to rename `config.json` to something else like `database.json` And a whole lot more. Let's see how you can use this file for custom configuration. @@ -395,18 +395,18 @@ module.exports = { }; ``` -With this config you are telling the CLI to: +With this config, you are telling the CLI to: -- Use `config/database.json` file for config settings; +- Use the `config/database.json` file for config settings; - Use `db/models` as models folder; - Use `db/seeders` as seeders folder; -- Use `db/migrations` as migrations folder. +- Use `db/migrations` as the migrations folder. ### Dynamic configuration -The configuration file is by default a JSON file called `config.json`. But sometimes you need a dynamic configuration, for example to access environment variables or execute some other code to determine the configuration. +The configuration file is by default a JSON file called `config.json`. But sometimes you need a dynamic configuration, for example, to access environment variables or execute some other code to determine the configuration. -Thankfully, the Sequelize CLI can read from both `.json` and `.js` files. This can be setup with `.sequelizerc` file. You just have to provide the path to your `.js` file as the `config` option of your exported object: +Thankfully, the Sequelize CLI can read from both `.json` and `.js` files. This can be setup with the `.sequelizerc` file. You just have to provide the path to your `.js` file as the `config` option of your exported object: ```js const path = require('path'); @@ -504,7 +504,7 @@ There are three types of storage that you can use: `sequelize`, `json`, and `non #### Migration Storage -By default the CLI will create a table in your database called `SequelizeMeta` containing an entry for each executed migration. To change this behavior, there are three options you can add to the configuration file. Using `migrationStorage`, you can choose the type of storage to be used for migrations. If you choose `json`, you can specify the path of the file using `migrationStoragePath` or the CLI will write to the file `sequelize-meta.json`. If you want to keep the information in the database, using `sequelize`, but want to use a different table, you can change the table name using `migrationStorageTableName`. Also you can define a different schema for the `SequelizeMeta` table by providing the `migrationStorageTableSchema` property. +By default, the CLI will create a table in your database called `SequelizeMeta` containing an entry for each executed migration. To change this behavior, there are three options you can add to the configuration file. Using `migrationStorage`, you can choose the type of storage to be used for migrations. If you choose `json`, you can specify the path of the file using `migrationStoragePath` or the CLI will write to the file `sequelize-meta.json`. If you want to keep the information in the database, using `sequelize`, but want to use a different table, you can change the table name using `migrationStorageTableName`. Also, you can define a different schema for the `SequelizeMeta` table by providing the `migrationStorageTableSchema` property. ```json { @@ -534,7 +534,7 @@ By default the CLI will create a table in your database called `SequelizeMeta` c #### Seed Storage -By default the CLI will not save any seed that is executed. If you choose to change this behavior (!), you can use `seederStorage` in the configuration file to change the storage type. If you choose `json`, you can specify the path of the file using `seederStoragePath` or the CLI will write to the file `sequelize-data.json`. If you want to keep the information in the database, using `sequelize`, you can specify the table name using `seederStorageTableName`, or it will default to `SequelizeData`. +By default, the CLI will not save any seed that is executed. If you choose to change this behavior (!), you can use `seederStorage` in the configuration file to change the storage type. If you choose `json`, you can specify the path of the file using `seederStoragePath` or the CLI will write to the file `sequelize-data.json`. If you want to keep the information in the database, using `sequelize`, you can specify the table name using `seederStorageTableName`, or it will default to `SequelizeData`. ```json { @@ -580,4 +580,4 @@ Use the command like so: `npm run migrate:up -- --url ` ### Programmatic usage -Sequelize has a sister library called [umzug](https://github.com/sequelize/umzug) for programmatically handling execution and logging of migration tasks. +Sequelize has a sister library called [umzug](https://github.com/sequelize/umzug) for programmatically handling the execution and logging of migration tasks.