Database migrations with TypeORM
When working with relational databases, we define the structure of the data rather strictly. For example, we need to specify the format of every table along…
When working with relational databases, we define the structure of the data rather strictly. For example, we need to specify the format of every table along with fields, relations, indexes, and other structures. By doing that, we also tell the database how to validate the incoming data. It is crucial to think about the structure of our database carefully. Even if we do that, the requirements that our application has to meet change. Because of the above, we rarely can avoid having to modify the structure of our database. When doing that, we need to be careful not to lose any existing data. With database migrations, we can define a set of controlled changes that aim to modify the structure of the data. They can include adding or removing tables, changing columns, or changing the data types, for example. While we could manually run SQL queries that make the necessary adjustments, this is not the optimal approach. Instead, we want our migrations to be easy to repeat across different application environments. Also, we need to acknowledge that modifying the structure of the database is a delicate process where things can go wrong and damage the existing data. Fortunately, writing database migrations includes committing them to the repository. Therefore, they can undergo a rigorous review before merging to the master branch. In this article, we go through the idea of migrations and learn how to perform them with TypeORM. Working with migrations using TypeORM When configuring TypeORM, we can set the synchronize property to true. This causes TypeORM to synchronize the database with our entities automatically. However, using it in production is highly discouraged because it might lead to unexpected data loss. Instead, TypeORM has a tool that helps us create and run migrations. Unfortunately, its migration documentation is outdated and does not match the latest version. Configuring the TypeORM CLI To start working with migrations using TypeORM, we need to properly configure its command line interface (CLI). To do that, we need to create a designated configuration file. typeOrm.config.ts import { DataSource } from 'typeorm'; import { ConfigService } from '@nestjs/config'; import { config } from 'dotenv'; config(); const configService = new ConfigService(); export default new DataSource({ type: 'postgres', host: configService.get('POSTGRES_HOST'), port: configService.get('POSTGRES_PORT'), username: configService.get('POSTGRES_USER'), password: configService.get('POSTGRES_PASSWORD'), database: configService.get('POSTGRES_DB'), entities: [], }); Above, we use dotenv to make sure the ConfigService loaded the environment variables before using it. We also need to add some entries to the scripts in our package.json. package.json "scripts": { "typeorm": "ts-node ./node_modules/typeorm/cli", "typeorm:run-migrations": "npm run typeorm migration:run -- -d ./typeOrm.config.ts", "typeorm:generate-migration": "npm run typeorm -- -d ./typeOrm.config.ts migration:generate ./migrations/$npm_config_name", "typeorm:create-migration": "npm run typeorm -- migration:create ./migrations/$npm_config_name", "typeorm:revert-migration": "npm run typeorm -- -d ./typeOrm.config.ts migration:revert", ... } Unfortunately, the $npm_config feature is not supported by yarn. Generating our first migration Let’s define a straightforward entity of a post. post.entity.ts import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm'; @Entity() class PostEntity { @PrimaryGeneratedColumn('identity', { generatedIdentity: 'ALWAYS', }) id: number; @Column() title: string; @Column() content: string; } export default PostEntity; If you want to know more about identity columns, check out Serial type versus identity columns in PostgreSQL and TypeORM There is a significant caveat regarding the entities directory in our configuration. Let’s take a look at our NestJS database configuration. database.module.ts import { Module } from '@nestjs/common'; import { TypeOrmModule } from '@nestjs/typeorm'; import { ConfigModule, ConfigService } from '@nestjs/config'; @Module({ imports: [ TypeOrmModule.forRootAsync({ imports: [ConfigModule], inject: [ConfigService], useFactory: (configService: ConfigService) => ({ type: 'postgres', host: configService.get('POSTGRES_HOST'), port: configService.get('POSTGRES_PORT'), username: configService.get('POSTGRES_USER'), password: configService.get('POSTGRES_PASSWORD'), database: configService.get('POSTGRES_DB'), entities: [], autoLoadEntities: true, }), }), ], }) class DatabaseModule {} export default DatabaseModule;The @nestjs/typeorm library implements the autoLoadEntities that analyzes our NestJS application and identifies all of our entities. Unfortunately, the basic TypeORM configuration can’t do that. We still need to add the entities we don’t use through TypeOrmModule.forFeature() to the entities array. Because of the above, we need to manually add the PostEntity to our entities array in our CLI configuration. typeOrm.config.ts import { DataSource } from 'typeorm'; import { ConfigService } from '@nestjs/config'; import { config } from 'dotenv'; import PostEntity from './src/posts/post.entity'; config(); const configService = new ConfigService(); export default new DataSource({ type: 'postgres', host: configService.get('POSTGRES_HOST'), port: configService.get('POSTGRES_PORT'), username: configService.get('POSTGRES_USER'), password: configService.get('POSTGRES_PASSWORD'), database: configService.get('POSTGRES_DB'), entities: [PostEntity], }); We might be able to figure out a better approach if the CLI would support asynchronous DataSource creation. Once the pull request with the improvement is merged, we could create a NestJS application in our typeOrm.config.ts file and take advantage of the autoLoadEntities property. Once we have all of the above set up, we can use the migration:generate command to let TypeORM generate the migration file.npm run typeorm:generate-migration --name=CreatePostRunning the migration command creates a file with the code that can bring our database from one state to another and back. Its filename consists of the current timestamp followed by the name provided when using the migration:generate command. 1658694616973-CreatePost.ts import { MigrationInterface, QueryRunner } from 'typeorm'; export class CreatePost1658694616973 implements MigrationInterface { name = 'CreatePost1658694616973'; public async up(queryRunner: QueryRunner): Promise