Forem: Dawit Girma

One Codebase, Multiple Environments: Mastering Env Config in NestJS

Dawit Girma — Thu, 16 Apr 2026 16:46:32 +0000

Have you ever wondered:

“Can I tell NestJS which environment variables to load when running my app?”

The simple answer is: yes, you absolutely can.

This is not one of my major deep-dive articles, but I wanted to share it because it used to be a real headache for me—and it might be for you as well.

At our company, we constantly switch between local, development, and production databases. What we used to do was far from ideal:

Comment one .env file
Uncomment another
Repeat the same process again and again

It worked, but it was messy, error-prone, and frustrating.
Until I found a cleaner and more scalable approach.

Step 1: Install Required Packages

We need two packages:

@nestjs/config for loading environment variables
cross-env for handling NODE_ENV across platforms

npm install @nestjs/config cross-env

Step 2: Create Multiple .env Files

Create environment-specific files such as:

.env.local
.env.test
.env.production

You can create as many as needed depending on your workflow.

Step 3: Define Scripts in package.json

"start:test": "cross-env NODE_ENV=test nest start --watch",
"start:local": "cross-env NODE_ENV=local nest start --watch"

The key idea:

The value of NODE_ENV must match the suffix of your .env file.
For example:
NODE_ENV=test loads .env.test
NODE_ENV=local loads .env.local

Step 4: Configure NestJS

In your app.module.ts, add:

ConfigModule.forRoot({
 envFilePath: `.env.${process.env.NODE_ENV}`,
 isGlobal: true,
}),

This tells NestJS to dynamically load the correct environment file based on NODE_ENV.

Step 5: Run Your Application

Now you can run your app in different environments easily:

npm run start:test 
npm run start:local

Or any other environment you define:

npm run start:other

Final Thoughts

What used to be a repetitive and error-prone process is now clean and predictable.

No more commenting and uncommenting configuration files.

No more accidental connections to the wrong database.

Just one codebase running across multiple environments in a controlled way.

Contact

If you have any questions, feel free to reach out:

LinkedIn: https://linkedin.com/in/dawit-girma-7b8867228/
Email: realdavis7779@gmail.com
GitHub: https://github.com/dedawit

Mastering Cron Jobs in NestJS: A Complete Guide with Real Examples (and Related Scheduling Mechanisms)

Dawit Girma — Sat, 11 Apr 2026 13:47:58 +0000

How do you automatically send daily reports to users without manual intervention?
How can a system periodically clean up expired data such as sessions or tokens?
What is the most reliable way to execute a task every midnight?

For these types of problems, cron jobs provide an effective and scalable solution.

Cron jobs are a scheduling mechanism used to automate repetitive tasks in software systems by executing code at predefined times or intervals. Instead of relying on manual triggers or user actions, cron jobs enable applications to handle background operations such as:

Sending emails
Cleaning expired data
Generating reports
Synchronizing with external services

This approach improves efficiency, minimizes human error, and ensures that critical tasks run consistently and on time.

In modern backend development, frameworks like NestJS provide built-in support for task scheduling, allowing developers to implement cron-based automation in a clean, structured, and scalable way.

This article explores how to use cron jobs in NestJS, including:

Declarative scheduling
Dynamic scheduling
Interval-based execution
Timeout-based execution

Prerequisites

Basic knowledge of NestJS

Project Setup

Create a New NestJS Application

nest new nestjs-cron

Install Scheduling Dependency

npm install --save @nestjs/schedule

Configure Schedule Module

Update your app.module.ts:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ScheduleModule } from '@nestjs/schedule';

@Module({
 imports: [ScheduleModule.forRoot()],
 controllers: [AppController],
 providers: [AppService],
})
export class AppModule {}

Now, we are all done with the setup, so we can create declarative and dynamic cron jobs.

Declarative Cron Jobs

Declarative cron jobs are defined before the application starts and run automatically based on a schedule.

Cron Expression Format

A cron expression typically consists of 6 fields:

*  *  *  *  *  *
|  |  |  |  |  |
|  |  |  |  |  └── Day of Week (0 - 7) (Sunday = 0 or 7)
|  |  |  |  └───── Month (1 - 12)
|  |  |  └──────── Day of Month (1 - 31)
|  |  └─────────── Hour (0 - 23)
|  └────────────── Minute (0 - 59)
└───────────────── Second (0 - 59)

Note: The seconds field is optional in some implementations.

The asterisk (*) represents “every” value.

For example:

* in the minute field → every minute
* * * * * → runs every minute

If interpreting cron expressions becomes challenging, you can use online tools such as crontab.guru to simplify the process. This tool allows you to input or modify cron expression values and instantly displays a human-readable explanation of the schedule. By adjusting the fields, you can quickly understand how each change affects execution timing. An illustrative example is shown below.

NestJS also provides predefined expressions for readability using CronExpression enum. This approach is easier to understand but less flexible than custom expressions. E.g.

CronExpression.EVERY_10_MINUTES

Below is example service created and imported in app.module.ts to illustrate.

import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';


@Injectable()
export class TestCronService {
 private readonly logger = new Logger(TestCronService.name);


 // Runs every minute using asterisk expression
 @Cron('* * * * *', {
   name: 'asterisk-every-minute',
   timeZone: 'Africa/Addis_Ababa',
 })
 handleAsteriskEveryMinute() {
   this.logger.log('Running cron: asterisk-every-minute');
 }


 // Runs every minute using CronExpression enum
 @Cron(CronExpression.EVERY_MINUTE, {
   name: 'enum-every-minute',
   timeZone: 'Africa/Addis_Ababa',
 })
 handleEnumEveryMinute() {
   this.logger.log('Running cron: enum-every-minute');
 }
}

And the provider section of app.module.ts should look like

 providers: [AppService, TestCronService],

And finally run your program, you should see logs of the above two cron jobs. Like

Declarative Intervals

Intervals allow repeated execution at fixed time intervals using setInterval() internally. Example code and log image is provided below.

 // Runs every 2 seconds using declarative interval
 @Interval('every-2-seconds', 2000)
 handleEvery2Seconds() {
   this.logger.log('declarative interval every 2 seconds (2000ms)');
 }

Declarative Timeout

Timeouts execute a task only once after a specified delay. Internally, they rely on JavaScript’s setTimeout() function to schedule the execution.

 // Runs once after 5 seconds using declarative timeout
 @Timeout('after-5-seconds', 5000)
 handleAfter5Seconds() {
   this.logger.log('declarative timeout after 5 seconds (5000ms)');
 }

Dynamic cron Jobs

Dynamic cron jobs enable runtime management of scheduled tasks, allowing you to create, retrieve, update, or delete cron jobs while the application is running. To perform these operations, NestJS provides the SchedulerRegistry API, which must be injected into your service to gain programmatic control over the scheduling system.

Key methods

addCronJob() – register a job
getCronJob() – retrieve a job
deleteCronJob() – remove a job

Cron job controls after we get cron job by name

stop() – stop execution
start() – restart job
setTime() – update schedule
lastDate() – last execution time
nextDate() – next execution time

Example code is given below with its log.

import { Injectable, Logger } from '@nestjs/common';
import { SchedulerRegistry, Timeout } from '@nestjs/schedule';
import { CronJob, CronTime } from 'cron';
import { DateTime } from 'luxon';


@Injectable()
export class DynamicCronService {
 private readonly logger = new Logger(DynamicCronService.name);


 constructor(private readonly schedulerRegistry: SchedulerRegistry) {}


 // Creates dynamic-job after 10 seconds and demonstrates all scheduler methods
 @Timeout('create-dynamic-cron', 10000)
 async createDynamicCron() {
   const job = new CronJob('* * * * * *', () => {
     this.logger.log('[dynamic-job] tick');
   });


   this.schedulerRegistry.addCronJob('dynamic-job', job);
   job.start();
   this.logger.log('dynamic-job created and started (every second)');


   const cronJob = this.schedulerRegistry.getCronJob('dynamic-job');


   // stop() - stops the running cron job
   cronJob.stop();
   this.logger.log('stop()     — dynamic-job stopped');


   // start() - restarts the stopped cron job
   cronJob.start();
   this.logger.log('start()    — dynamic-job restarted');


   // setTime() - stops the job and restarts it with a new schedule (every 5 seconds)
   cronJob.setTime(new CronTime('*/5 * * * * *'));
   cronJob.start();
   this.logger.log(
     'setTime()  — schedule changed to every 5 seconds, job restarted',
   );


   // wait 5 seconds so the job executes at least once before checking lastDate()
   await new Promise((resolve) => setTimeout(resolve, 5000));


   // lastDate() - returns last DateTime of execution (null if not yet executed)
   this.logger.log(
     `lastDate() — last execution: ${cronJob.lastDate() ? DateTime.fromJSDate(cronJob.lastDate()!) : 'not yet executed'}`,
   );


   // nextDate() - returns next DateTime of execution as a luxon DateTime
   this.logger.log(`nextDate() — next execution: ${cronJob.nextDate()}`);
 }


 // Stops and deletes dynamic-job after 30 seconds
 @Timeout('delete-dynamic-cron', 30000)
 deleteDynamicCron() {
   const cronJob = this.schedulerRegistry.getCronJob('dynamic-job');
   cronJob.stop();
   this.schedulerRegistry.deleteCronJob('dynamic-job');
   this.logger.log('dynamic-job stopped and deleted after 30 seconds');
 }
}

Dynamic Intervals

Intervals can be managed at runtime using the SchedulerRegistry API, allowing you to create, retrieve, and delete named intervals dynamically. For clarity, the previous provider can be replaced with a dedicated dynamic interval service, which should then be registered in app.module.ts.

The following example demonstrates the complete lifecycle of a dynamic interval: an interval is created after 5 seconds, retrieved for reference, and automatically removed after running for 20 seconds.


import { Injectable, Logger } from '@nestjs/common';
import { SchedulerRegistry, Timeout } from '@nestjs/schedule';


@Injectable()
export class DynamicIntervalService {
 private readonly logger = new Logger(DynamicIntervalService.name);


 constructor(private readonly schedulerRegistry: SchedulerRegistry) {}


 // Creates dynamic-interval after 5 seconds and registers it with SchedulerRegistry
 @Timeout('create-dynamic-interval', 5000)
 createDynamicInterval() {
   const interval = setInterval(() => {
     this.logger.log('[dynamic-interval] tick every 2 seconds');
   }, 2000);


   this.schedulerRegistry.addInterval('dynamic-interval', interval);
   this.logger.log('dynamic-interval created and started (every 2 seconds)');


   // getInterval() - retrieves the registered interval reference
   const ref = this.schedulerRegistry.getInterval('dynamic-interval');
   this.logger.log(`getInterval() — interval ref retrieved, id: ${ref}`);
 }


 // Deletes dynamic-interval after 20 seconds
 @Timeout('delete-dynamic-interval', 20000)
 deleteDynamicInterval() {
   this.schedulerRegistry.deleteInterval('dynamic-interval');
   this.logger.log('dynamic-interval deleted after 20 seconds');
 }
}

Dynamic Timeouts

Timeouts can also be managed dynamically at runtime using the SchedulerRegistry API, which allows you to create, retrieve, and delete timeout tasks programmatically. For clarity, you can replace the previous provider with a dedicated dynamic timeout service and register it in app.module.ts.

The following example illustrates the full lifecycle of a dynamic timeout: a timeout is created after 5 seconds, its reference is retrieved for inspection, and it is subsequently deleted after 20 seconds.


import { Injectable, Logger } from '@nestjs/common';
import { SchedulerRegistry, Timeout } from '@nestjs/schedule';


@Injectable()
export class DynamicTimeoutService {
 private readonly logger = new Logger(DynamicTimeoutService.name);


 constructor(private readonly schedulerRegistry: SchedulerRegistry) {}


 // Creates dynamic-timeout after 5 seconds and registers it with SchedulerRegistry
 @Timeout('create-dynamic-timeout', 5000)
 createDynamicTimeout() {
   const timeout = setTimeout(() => {
     this.logger.log('[dynamic-timeout] fired after 10 seconds');
   }, 10000);


   this.schedulerRegistry.addTimeout('dynamic-timeout', timeout);
   this.logger.log(
     'dynamic-timeout created and registered (fires in 10 seconds)',
   );


   // getTimeout() - retrieves the registered timeout reference
   const ref = this.schedulerRegistry.getTimeout('dynamic-timeout');
   this.logger.log(`getTimeout() — timeout ref retrieved, id: ${ref}`);
 }


 // Deletes dynamic-timeout after 20 seconds (before it fires)
 @Timeout('delete-dynamic-timeout', 20000)
 deleteDynamicTimeout() {
   this.schedulerRegistry.deleteTimeout('dynamic-timeout');
   this.logger.log('dynamic-timeout deleted after 20 seconds ');
 }
}

Conclusion

NestJS provides a powerful and flexible scheduling system through @nestjs/schedule, enabling developers to implement:

Cron-based automation
Interval-based execution
Timeout-based execution
Runtime (dynamic) scheduling control

By leveraging these features, you can build reliable backend systems that automate repetitive tasks efficiently and maintain consistent system behavior.

Contact

If you have any questions, feel free to reach out:

LinkedIn: https://linkedin.com/in/dawit-girma-7b8867228/
Email: realdavis7779@gmail.com
Github: https://github.com/dedawit

The final code is available at public repository:
https://github.com/dedawit/nestjs-cron.git

References

Advanced Postman Concepts for Efficient API Testing

Dawit Girma — Thu, 12 Mar 2026 18:42:53 +0000

Introduction

Postman is a widely used API client that enables developers to test APIs and verify responses efficiently. While many developers use Postman for basic API requests, the platform offers a wide range of advanced features that can significantly simplify and accelerate the API testing process.

In this article, we will explore several advanced Postman techniques that help streamline API testing and improve productivity. These features include dynamic URLs, token-based authentication using variables, sending files in request bodies, using randomly generated variables, and managing path and query parameters effectively.

Prerequisites

Before reading this article, it is recommended that you have:

Basic knowledge of APIs
Basic familiarity with Postman

Advanced Features Covered

In this article, we will explore the following advanced Postman features:

Dynamic URLs using environments
Token-based authentication using variables
Sending files in request bodies
Randomly generated variables for test data
Path parameters
Query parameters

Each of these features helps make API testing more flexible, maintainable, and efficient.

Dynamic URLs Using Environments

When testing APIs, many developers paste the full URL directly into the request input field. However, this approach is not recommended. The best practice is to store the base URL in a Postman environment variable and reference it within requests.

This approach is particularly useful when switching between environments, such as local development, staging, or production. Instead of modifying every request URL, you only need to update the base URL in the environment.

Steps to Create an Environment Variable

In Postman, go to the top left section of the sidebar.

Click the plus (+) icon.
Select Environment.
Create a new environment.

You will see a table where you can define variable–value pairs.

Example:

Once this variable is defined, instead of writing the full URL such as:

http://localhost:3003/auth/login

you can write:

{{BASE_URL}}/auth/login

Now, if the backend server changes (for example switching from local development to a remote server), you only need to update the BASE_URL variable.

Token-Based Authentication Using Variables

Many developers manually copy the access token from the login response and paste it into every authenticated request. This approach is inefficient and prone to errors.

A better approach is to store the access token in an environment variable automatically after login. Once stored, it can be reused in all authenticated requests.

Steps

Open the Scripts section in the Postman request page.
Add a script to extract the token from the response.

Example:

pm.environment.set("ACCESS_TOKEN", pm.response.json().accessToken);

This script saves the access token into the environment variable ACCESS_TOKEN.

If you work with multiple roles (for example, admin and user), you can store multiple tokens:

ACCESS_TOKEN_ADMIN
ACCESS_TOKEN_USER

Using the Token in Requests

In the Authorization section of your request:

Choose Bearer Token

Use the variable:

{{ACCESS_TOKEN_ADMIN}}

Now, whenever you log in again and receive a new token, the variable updates automatically. There is no need to manually copy and paste tokens.

Sending Files in the Request Body

Files cannot be sent as part of a JSON request body in the raw section. Instead, Postman provides support for file uploads using form-data.

Steps to Send Files

Go to the Body tab.
Select form-data.

You will see two columns:

Key
Value

In form-data, values can be either:

Text
File

There is a small dropdown selector in the key column where you can switch between Text and File.

If you choose File, Postman will allow you to:

Upload a file from your system
Select a file from Postman Cloud

For example, a request body might contain:

This format allows the backend API to receive both files and additional fields in the same request.

Randomly Generated Variables for Request Data

During API testing, developers often reuse the same data repeatedly, such as the same name, email, or city. This can create problems when testing systems that require unique values.

Postman provides dynamic variables that automatically generate random data for each request.

Examples include:

$randomPhoneNumber
$randomIP
$randomBankAccount
$randomEmail
$randomFirstName

Example request body:

Using dynamic variables helps generate unique test data automatically, making it easier to test user creation, registrations, and other API operations.

You can find a full list of dynamic variables in the Postman documentation.

Path Parameters

Many APIs use path parameters, typically for resource identifiers such as IDs.

A common approach is to hardcode the ID directly in the URL. However, this makes testing less flexible.

For example:

/users/fac9a13a-3b01-4052-9965-fb2479b3150e

Instead, you can define the parameter using a variable - using colon and name of variable:

/users/:id

Postman will automatically create an input field in the Path Variables section where you can enter the value of id.

This makes it easy to test different resource IDs without modifying the request URL manually.

Query Parameters

Query parameters are commonly added manually in the URL using a question mark (?) followed by key–value pairs.

Example:

/users?role=admin&page=2

However, manually editing URLs can become difficult when multiple parameters are involved.

Postman provides a Query Params section that allows you to define query parameters using key–value pairs.

Example:

Postman automatically constructs the request URL for you. This approach improves readability and makes parameter management easier.

Conclusion

Postman provides powerful tools that go beyond simple API request testing. By using advanced features such as environment variables, automated token management, dynamic variables, and structured request parameters, developers can significantly improve the efficiency and maintainability of their API testing workflows.

In this article, we explored several practical techniques that simplify API testing, particularly for backend developers working with authentication, dynamic data, and flexible request configurations.

Mastering these features can greatly enhance your development and debugging process.

Contact

If you have any questions, feel free to reach out:

LinkedIn:

https://linkedin.com/in/dawit-girma-7b8867228/

Email:

realdavis7779@gmail.com

GitHub:

https://github.com/dedawit

Reference:

learning.postman.com

Entity-Attribute-Value (EAV) Model

Dawit Girma — Tue, 10 Feb 2026 20:17:02 +0000

(Example: Content Management System)

Have you ever faced a database design problem where the attributes of an entity vary widely across records?

If yes, this article is for you.

The Entity–Attribute–Value (EAV) model is a database design pattern that allows us to define entity attributes at runtime. In many real-world systems, a table can contain millions of records, where:

Some entities have attributes X, Y, Z
Others have completely different attributes
Many attributes apply only to a small subset of records

In such cases, using a traditional relational schema often leads to many NULL values and frequent schema changes.

With the EAV model, instead of adding new columns or storing NULLs, we define attributes separately and assign values only when they apply to a specific entity instance.

EAV models are commonly used in systems such as:

E-commerce platforms
Real-estate management systems
Content management systems (CMS)
Product catalogs

In this article, we will explain how the Entity–Attribute–Value model works by using a Content Management System (CMS) as a practical example.

Use Cases

The EAV model is powerful only when used in the right scenarios. Below are the main reasons to consider using EAV in your database design.

When to Use EAV

- Frequently changing attributes

When entities have many attributes that evolve over time (new attributes are added frequently).

- Sparse data

When most entities use only a small subset of available attributes, and the rest would otherwise be stored as NULL.

- Custom attributes

When administrators or users need to define custom attributes at runtime without requiring database schema changes.

When Not to Use EAV

- Stable and well-defined attributes

If the attributes are fixed and rarely change, a traditional relational schema is a better choice.

- High-performance requirements

EAV models often require multiple joins, which can negatively impact query performance.

- Complex reporting and analytics

Writing reports and analytical queries is more difficult and less efficient in EAV-based schemas.

Important note:

Using EAV does not mean every table in your system should follow this model.

In practice, the best approach is often a hybrid model, combining traditional tables with EAV tables based on the nature of each entity.

Prerequisites

Basic understanding of database systems
Familiarity with relational databases and ER diagrams

Project Setup

To illustrate the EAV model, we will design an Entity Relationship Diagram (ERD) for a simple content management system.

Understanding the EAV ERD

The classic EAV model consists of three main tables:

Figure 1.0: Entity–Attribute–Value ER Diagram

- Entity

Represents the main object whose attributes can vary over time.

- Attribute

Stores the possible attributes that an entity can have.

- AttributeValue

Stores the actual value of a specific attribute for a specific entity.

This structure allows attributes to be added dynamically without altering the database schema.

Example: Content Management System (CMS)

A Content Management System is used to create, manage, and publish different types of digital content such as:

Blog posts
Pages
Events
Courses
Job postings

Each content type has its own unique attributes. For example:

An Event has a location and start date
A Job has a salary and employment type
A Page may not require either

To support this flexibility without constant schema changes, the EAV model is an ideal solution.

Below is a simplified ERD for a CMS using the EAV model
(Note: This diagram may require refinement before production use).

Figure 1.1: EAV Model for a Content Management System

Tables Overview

- Content

Represents the actual content entity with dynamic attributes.

- ContentType

Defines the type of content (e.g., Blog, Event, Job).

- Attribute

Defines attributes specific to a content type.

- ContentAttributeValue

Stores the value of a specific attribute for a specific content item.

Real-World Table Instances

Table ContentType

Table Content

Table Attribute

Table ContentAttributeValue (Core table)

From these examples, you can clearly see how the EAV model allows different content types to store only the attributes that apply to them—without wasting space or changing the schema.

Implementation

The final step is implementing this model in a programming language or framework of your choice. This part is intentionally left to the reader, as covering it would significantly extend the length of this article.

Conclusion

The Entity–Attribute–Value (EAV) model is a flexible database design pattern that helps manage dynamic and evolving attributes over time.

In this article, we explored:

When to use and avoid EAV
The core structure of the EAV model
A real-world example using a Content Management System

When applied correctly—often as part of a hybrid design—EAV can be a powerful solution for systems that require high flexibility.

Contact

If you have any questions, feel free to reach out:

LinkedIn: https://linkedin.com/in/dawit-girma-7b8867228/
Email: realdavis7779@gmail.com
Github: https://github.com/dedawit

References

A Practical Guide to Database Migrations in NestJS (TypeORM)

Dawit Girma — Tue, 13 Jan 2026 11:15:01 +0000

Database migrations are essential for managing database schemas (tables, columns, relationships) and data instances (records inside tables) in a safe and controlled manner. Each migration consists of two methods:

- up - applies actual change
- down - reverts the change made by the up method

Many NestJs developers struggle with setting up migrations correctly. In this article, we will walk through creating, running and managing migrations in NestJs using TypeORM with PostgresSQL, using practical, step by step examples.

Prerequisites

Before starting, make sure you have the following:

Basic knowledge of NestJs
NodeJs 18+
NestJs 10+
Basic knowledge of TypeORM
Basic knowledge of PostgresSQL

Project Setup

We will create a minimal NestJs application to demonstrate migrations step by step.

1. Create a New NestJs Application

Run the following command to create a new NestJs project:

nest new nestjs-migration

2. Configure TypeORM

Create a config folder in the project root and create a file named typeorm.config.ts.
Install the required packages (TypeORM, PostgresSQL driver and configuration loader):

npm i @nestjs/typeorm @nestjs/config typeorm pg

Now paste the following code to config/typeorm.config.ts:

import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { DataSource, DataSourceOptions } from 'typeorm';

ConfigModule.forRoot({ isGlobal: true });

const configService = new ConfigService();
const DB_PORT = configService.getOrThrow<number>('DATABASE_PORT');

export const typeOrmConfig: TypeOrmModuleOptions = {
  type: 'postgres',
  host: configService.getOrThrow<string>('HOST_NAME'),
  port: DB_PORT,
  username: configService.getOrThrow<string>('DATABASE_USERNAME'),
  password: configService.getOrThrow<string>('DATABASE_PASSWORD'),
  database: configService.getOrThrow<string>('DATABASE_NAME'),
  entities: [__dirname + '/../**/*.entity.{js,ts}'],
  migrations: [__dirname + '/../src/migrations/*.{js,ts}'],
  synchronize: true,
};

export const dataSource = new DataSource(
  typeOrmConfig as DataSourceOptions,
);

3. Environment Variables

Create a .env file in the project root and add the following values (replace them with your own credentials).
Make sure to create a PostgresSQL database named nestjs_migration.

HOST_NAME=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=your_username
DATABASE_PASSWORD=your_password
DATABASE_NAME=nestjs_migration

4. Create entity

Create a file named user.entity inside the src folder:

import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity('user')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;
}

5. Register TypeORM in AppModule

Update app.module.ts as:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { typeOrmConfig } from 'config/typeorm.config';
import { User } from './user.entity';

@Module({
  imports: [
    TypeOrmModule.forRoot(typeOrmConfig),
    TypeOrmModule.forFeature([User]),
  ],
})
export class AppModule {}

6. Add TypeORM Migration Scripts

Add the following scripts to the scripts section of package.json.

Linux / macOS

"typeorm": "ts-node ./node_modules/typeorm/cli",
"migration:run": "npm run typeorm migration:run -- -d ./config/typeorm.config.ts",
"migration:generate": "npm run typeorm -- -d ./config/typeorm.config.ts migration:generate ./src/migrations/$npm_config_name",
"migration:create": "npm run typeorm -- migration:create ./src/migrations/$npm_config_name",
"migration:revert": "npm run typeorm -- -d ./config/typeorm.config.ts migration:revert"

Windows

"typeorm": "ts-node ./node_modules/typeorm/cli",
"migration:run": "npm run typeorm migration:run -- -d ./config/typeorm.config.ts",
"migration:generate": "npm run typeorm -- -d ./config/typeorm.config.ts migration:generate ./src/migrations/%npm_config_name%",
"migration:create": "npm run typeorm -- migration:create ./src/migrations/%npm_config_name%",
"migration:revert": "npm run typeorm -- -d ./config/typeorm.config.ts migration:revert"

7. Initial Database Sync

Run the application to create the initial user table:

npm run start:dev

Ensure synchronize:true is enabled in the database configuration at this stage.

Understanding Migration Commands

1. typeorm

"typeorm": "ts-node ./node_modules/typeorm/cli"

This command allows us to run the TypeORM CLI using ts-node, enabling the execution of Typescript files without building the project. All migrations rely on this command.

2. migration:generate

Before generating migrations, set synchronize to false to prevent TypeORM from automatically applying schema changes.
Let us add a new username field to User entity:

@Column()
username: string;

Now generate a migration:


npm run migration:generate --name=username-field-addition

The command generates migration similar to:

import { MigrationInterface, QueryRunner } from 'typeorm';

export class UsernameFieldAddition1768070224042
  implements MigrationInterface
{
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(
      `ALTER TABLE "user" ADD "username" character varying NOT NULL`,
    );
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(
      `ALTER TABLE "user" DROP COLUMN "username"`,
    );
  }
}

3. migration:run

npm run migration:run

This command executes all pending migrations by running their up methods. TypeORM tracks executed migrations in a dedicated table to prevent re-runnig them.

In order to apply the changes in the generated migration above, we need to execute it. Hence, run the migration:run command to add username in user table in the database.

4. migration:revert

npm run migration:revert

This runs the down method of the migration, reverting the changes. After reverting, delete the migration file to avoid reapplying it later.

If we run the migration:revert command above, the username field will be removed.

5. migration:create

The command creates empty migration for manual changes, commonly used for inserting initial data (e.g. a superadmin user account)


npm run migration:create --name=superadmin-user

The above migration creates a migration with the name superadmin-user. You can use any name you want.
Generated migration

import { MigrationInterface, QueryRunner } from 'typeorm';

export class SuperadminUser1768073019893
  implements MigrationInterface
{
  public async up(queryRunner: QueryRunner): Promise<void> {}

  public async down(queryRunner: QueryRunner): Promise<void> {}
}

Modify the above migration manually to insert superadmin user:

import { MigrationInterface, QueryRunner } from 'typeorm';

export class SuperadminUser1768073019893
  implements MigrationInterface
{
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(
      `
      INSERT INTO "user" (email, password)
      VALUES ($1, $2)
      ON CONFLICT (email) DO NOTHING
      `,
      ['superadmin@example.com', 'superadmin123'],
    );
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(
      `
      DELETE FROM "user"
      WHERE email = $1
      `,
      ['superadmin@example.com'],
    );
  }
}

Run the migration:

npm run migration:run

The superadmin user record will now exist in the database.

Conclusion

Database migrations are powerful tools for managing both the schema changes and data updates safely. This article demonstrated a practical and straightforward approach to handling migrations in NestJS with TypeORM, from setup to advanced use cases.

Contact

If you have any questions, feel free to reach out:

LinkedIn: https://linkedin.com/in/dawit-girma-7b8867228/
Email: realdavis7779@gmail.com
Github: https://github.com/dedawit

The final code is available at public repository:

https://github.com/dedawit/nestjs-migration.git

References

https://docs.nestjs.com/
https://typeorm.io/docs/migrations/why