Building Scalable NestJS REST APIs with PostgreSQL and Redis

Introduction

Building a backend that can scale from a prototype to a production system is one of the most common challenges for modern development teams. The NestJS framework has emerged as a leading choice for building efficient, reliable, and scalable server-side applications with Node.js. In this guide we will design and implement a production-ready NestJS REST API that uses PostgreSQL as the primary datastore and Redis for caching and session management. Whether you are migrating from Express or starting fresh, the patterns shown here will help you create a maintainable architecture.

We will cover core concepts such as modules, dependency injection, and pipes, then move into a layered architecture that separates concerns between controllers, services, and repositories. You will learn how to integrate TypeORM with PostgreSQL, add Redis caching to heavy endpoints, implement JWT authentication, and prepare the application for containerized deployment. By the end you will have a clear blueprint for your own NestJS REST API that can handle real traffic and evolve with your product requirements.

The combination of NestJS, PostgreSQL, and Redis is particularly powerful because it balances structure, relational integrity, and speed. NestJS provides opinionated patterns that reduce decision fatigue, PostgreSQL delivers ACID compliance and rich querying, and Redis offers sub-millisecond access to frequently used data. Together they form a stack trusted by startups and enterprises alike.

Table of Contents

• Core Concepts
• Architecture Overview
• Step-by-Step Guide
• Real-World Examples
• Production Code Examples
• Comparison Table
• Best Practices
• Common Mistakes
• Performance Tips
• Security Considerations
• Deployment Notes
• Debugging Tips
• FAQ
• Conclusion

Core Concepts

NestJS is a progressive Node.js framework that combines elements of object-oriented programming, functional programming, and reactive programming. It is built on top of Express by default but also supports Fastify. The framework uses decorators and metadata to define modules, controllers, and providers, relying heavily on dependency injection to manage the lifecycle of components. This design makes the codebase predictable and testable.

A module is a class annotated with @Module() that groups related controllers and providers. Controllers handle incoming requests and return responses, while providers (often services) contain business logic. The dependency injection container resolves and injects providers where needed, promoting testability and loose coupling. When you inject a service into a controller, NestJS automatically instantiates it as a singleton unless configured otherwise.

PostgreSQL is a powerful open-source relational database. In our API we will use TypeORM, a TypeScript-friendly ORM, to map entities to tables and run migrations. TypeORM provides repositories, query builders, and decorators that align well with NestJS patterns. Redis is an in-memory data structure store used here as a cache layer to reduce database load and as a fast key-value store for refresh tokens or rate-limit counters.

Understanding the request lifecycle is critical: a request hits a controller, the controller calls a service, the service may query a repository, and interceptors or pipes can transform or validate the data. Guards protect routes, and filters handle errors uniformly. Middleware can run before routes for logging or CORS. By leveraging these building blocks you avoid scattering cross-cutting logic across handlers.

Another key concept is configuration management. NestJS encourages the use of ConfigModule to inject typed configuration. This prevents hard-coded credentials and simplifies environment-specific behavior. Combined with validation pipes, the framework nudges you toward a clean, production-grade setup from day one.

Architecture Overview

We will use a modular monolith structure that can later be extracted into microservices if needed. The system consists of the following layers:

• API Gateway / Load Balancer: Terminates TLS and forwards requests to NestJS instances.
• Controller Layer: Validates input via DTOs and pipes, delegates to services.
• Service Layer: Encapsulates business rules, caching logic, and transactions.
• Repository Layer: TypeORM repositories abstract PostgreSQL queries.
• Cache Layer: Redis stores computed results and ephemeral tokens.
• Database Layer: PostgreSQL with proper indexing and connection pooling.

Each domain (users, products, orders) is a NestJS module. Cross-cutting concerns like logging, configuration, and authentication are global modules. The Redis client is injected as a provider so it can be mocked in tests. This separation ensures that a change in the caching strategy does not affect business logic, and database schema changes are isolated to the repository layer.

In a typical request, the load balancer routes to an instance. The controller validates the payload using a DTO decorated with class-validator rules. The service checks Redis for a cached result; on a miss it queries PostgreSQL via a repository, computes the response, stores it in Redis with a TTL, and returns it. Error filters catch any exceptions and format them consistently. This flow is repeated across domains, making the system easy to reason about.

For larger systems you can introduce CQRS or event-driven patterns, but for most CRUD-centric APIs the layered modular monolith is sufficient and far simpler to operate. The architecture described here is intentionally pragmatic.

Step-by-Step Guide

Follow these steps to scaffold and build the API.

1. Scaffold the Project

Use the Nest CLI to create a new workspace. The CLI sets up TypeScript, testing, and a default structure.

npm i -g @nestjs/clinest new nest-api && cd nest-apinpm install @nestjs/typeorm typeorm pg @nestjs/cache-manager cache-manager redis cache-manager-redis-yet @nestjs/jwt passport-jwt

2. Configure Environment

Create a .env file with database and redis credentials. Use the ConfigModule to load it globally. Define variables such as DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME, REDIS_HOST, REDIS_PORT, JWT_SECRET. Never commit the .env file to version control.

3. Setup TypeORM and PostgreSQL

Import TypeOrmModule.forRootAsync and read configuration from environment variables. Define entities such as User and Product. Set synchronize to false in production and rely on migrations.

4. Create Redis Cache Module

Register CacheModule with redis store and set TTL defaults. Inject CACHE_MANAGER into services. Make the module global so any service can use caching without re-importing.

5. Build Authentication

Implement JWT strategy, auth guard, and login endpoint that issues access and refresh tokens. Store refresh tokens in Redis with expiration. Protect sensitive routes with the guard.

6. Implement CRUD Services

For each domain, create a service with methods to list, create, update, and delete. Apply caching on read-heavy methods. Use transactions when multiple writes must succeed together.

7. Add Validation and Error Filters

Use class-validator DTOs and a global validation pipe. Create a custom exception filter for consistent error responses. Return problem-detail style JSON.

8. Write Tests

Unit test services with mocked repositories and integration test controllers with an in-memory PostgreSQL or a CI container. Aim for meaningful coverage of business rules.

9. Containerize

Write a multi-stage Dockerfile. Build the app, run migrations, and start the server. Use docker-compose for local development with PostgreSQL and Redis services.

Real-World Examples

Consider an e-commerce backend. The product catalog endpoint receives thousands of requests per minute. Without caching, each request triggers a SQL query joining categories and reviews. By caching the serialized result in Redis for 60 seconds, we cut database load by over 90% during traffic spikes. The slight staleness is acceptable for a catalog.

Another example is user profile updates. When a user changes their name, the service updates PostgreSQL and invalidates the Redis key for that user. This pattern keeps data consistent while still benefiting from cache. Invalidation logic should be centralized to avoid forgotten keys.

In a multi-instance deployment, Redis also acts as a shared store for refresh tokens, allowing any node to verify a token without sticky sessions. This enables horizontal scaling behind a load balancer. A similar pattern works for rate limiting: increment a counter in Redis per IP and block when the threshold is met.

A analytics dashboard is another case. Aggregation queries over large tables can be slow. You can run them on a read replica and cache the result for a few minutes. The API remains responsive even when underlying data is massive.

Production Code Examples

Below are realistic snippets following current NestJS 10 and TypeORM 0.3 practices.

App Module Configuration

import { Module } from '@nestjs/common';import { ConfigModule, ConfigService } from '@nestjs/config';import { TypeOrmModule } from '@nestjs/typeorm';import { CacheModule } from '@nestjs/cache-manager';import { redisStore } from 'cache-manager-redis-yet';import { UsersModule } from './users/users.module';@Module({  imports: [    ConfigModule.forRoot({ isGlobal: true }),    TypeOrmModule.forRootAsync({      inject: [ConfigService],      useFactory: (config: ConfigService) => ({        type: 'postgres',        host: config.get('DB_HOST'),        port: +config.get('DB_PORT'),        username: config.get('DB_USER'),        password: config.get('DB_PASS'),        database: config.get('DB_NAME'),        autoLoadEntities: true,        synchronize: false,        migrationsRun: true,      }),    }),    CacheModule.registerAsync({      isGlobal: true,      inject: [ConfigService],      useFactory: async (config: ConfigService) => ({        store: await redisStore({          socket: { host: config.get('REDIS_HOST'), port: config.get('REDIS_PORT') },          ttl: 60,        }),      }),    }),    UsersModule,  ],})export class AppModule {}

User Service with Caching

import { Injectable, NotFoundException } from '@nestjs/common';import { CACHE_MANAGER } from '@nestjs/cache-manager';import { Inject } from '@nestjs/common';import { Cache } from 'cache-manager';import { InjectRepository } from '@nestjs/typeorm';import { Repository } from 'typeorm';import { User } from './user.entity';@Injectable()export class UsersService {  constructor(    @InjectRepository(User) private repo: Repository,    @Inject(CACHE_MANAGER) private cache: Cache,  ) {}  async findOne(id: string): Promise {    const cacheKey = `user:${id}`;    const cached = await this.cache.get(cacheKey);    if (cached) return cached;    const user = await this.repo.findOne({ where: { id } });    if (!user) throw new NotFoundException('User not found');    await this.cache.set(cacheKey, user, 60);    return user;  }  async update(id: string, dto: Partial): Promise {    await this.repo.update(id, dto);    await this.cache.del(`user:${id}`);    return this.findOne(id);  }}

JWT Auth Guard

import { AuthGuard, PassportStrategy } from '@nestjs/passport';import { ExtractJwt, Strategy } from 'passport-jwt';import { Injectable } from '@nestjs/common';@Injectable()export class JwtStrategy extends PassportStrategy(Strategy) {  constructor() {    super({      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),      secretOrKey: process.env.JWT_SECRET,    });  }  async validate(payload: any) {    return { userId: payload.sub, email: payload.email };  }}

Custom Exception Filter

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';import { Response } from 'express';@Catch(HttpException)export class HttpExceptionFilter implements ExceptionFilter {  catch(exception: HttpException, host: ArgumentsHost) {    const ctx = host.switchToHttp();    const response = ctx.getResponse();    const status = exception.getStatus();    const message = exception.getResponse();    response.status(status).json({      success: false,      statusCode: status,      error: message,    });  }}

Comparison Table

Choosing the right Node.js framework affects long-term productivity. The table below compares NestJS with Express and Fastify for building REST APIs.

Best Practices

• Keep controllers thin; move logic to services. Controllers should only parse requests and format responses.
• Use DTOs with class-validator for input validation. This prevents malformed data from reaching the database.
• Make modules global only when necessary (Config, Cache, DB). Overusing global modules hides dependencies.
• Set explicit TTLs on cache entries and document invalidation. Always pair a write operation with cache deletion.
• Use database migrations instead of synchronize in production. Migrations are version-controlled and reversible.
• Centralize error handling with a global exception filter. Clients should receive consistent shapes.
• Write integration tests that use a real PostgreSQL instance in CI. Mocking the DB entirely can hide query bugs.
• Use environment-based configuration and secrets management. Never hard-code connection strings.
• Apply the principle of least privilege to database users. The API should connect with a role that cannot drop tables.
• Log structured JSON instead of plain text to simplify aggregation in ELK or Datadog.

Common Mistakes

• Using synchronize: true in production leads to unexpected schema drops or data loss.
• Storing large objects in Redis without TTL causes memory bloat and eviction of hot keys.
• Putting business logic inside controllers, making testing hard and duplication likely.
• Ignoring connection pool limits, causing PostgreSQL saturation under load.
• Returning entity objects directly, exposing sensitive fields like password hashes.
• Not handling Redis failures, causing cascading API errors when the cache is down.
• Over-caching mutable data, resulting in users seeing stale information.
• Skipping validation, allowing NoSQL injection style attacks through JSON fields.

Performance Tips

• Enable PostgreSQL connection pooling (default 10) and tune to workload. Monitor active connections.
• Use indexed columns for WHERE, JOIN, and ORDER BY. Run EXPLAIN ANALYZE on slow queries.
• Cache aggregated read endpoints with short TTLs. Use cache keys that include query params.
• Use select to fetch only needed fields in TypeORM to reduce payload size.
• Compress responses with a middleware or proxy. Gzip or Brotli saves bandwidth.
• Offload static file serving and TLS to Nginx or a CDN. Keep Node.js focused on dynamic work.
• Consider read replicas for heavy reporting queries to protect the primary writer.
• Use background jobs for expensive tasks like sending emails or generating PDFs.

Security Considerations

• Store JWT secret in a vault, not in source code. Rotate keys periodically.
• Use short-lived access tokens and rotate refresh tokens. Bind refresh tokens to device or IP hash.
• Validate and sanitize all user input via DTOs. Reject unknown properties.
• Enable CORS with explicit allowed origins. Do not use wildcard with credentials.
• Use Helmet or platform equivalents to set secure headers like CSP and X-Content-Type-Options.
• Rate-limit login endpoints using Redis counters to prevent brute force.
• Encrypt sensitive database fields at rest if required by compliance.
• Keep dependencies updated. Run npm audit and automated scanning in CI.

Deployment Notes

Containerize the API with a multi-stage Dockerfile. Build stage compiles TypeScript, runtime stage copies dist and node_modules. Use a separate migration job before starting the app to avoid race conditions. Deploy behind a load balancer with multiple replicas. Ensure Redis is backed by a managed service or a sentinel cluster for high availability.

Use Kubernetes liveness and readiness probes on /health endpoint. The readiness check should verify database and redis connectivity. Set NODE_ENV=production and enable --max-old-space-size appropriate to container memory. Capture SIGTERM to allow graceful shutdown of in-flight requests.

For environment-specific configuration, inject secrets as environment variables from your orchestrator. Never bake secrets into images. Use horizontal pod autoscaling based on CPU or custom metrics such as request latency.

Debugging Tips

• Enable NestJS debug logs with logger: ['error','warn','debug'] during development.
• Use TypeORM query logging to spot N+1 queries and missing indexes.
• Inspect Redis keys with redis-cli MONITOR during development to verify cache hits.
• Write a custom interceptor to log request/response cycles with correlation IDs.
• Use node --inspect with VS Code for breakpoints in async service methods.
• Add a health endpoint that returns detailed dependency status for quick triage.

FAQ

What is the best way to structure a NestJS REST API?

Use feature modules with clear separation between controllers, services, and repositories. Keep cross-cutting providers global and avoid circular dependencies by using forwardRef only when necessary. Place shared utilities in a common module.

Should I use PostgreSQL or MongoDB with NestJS?

If your data is relational and benefits from transactions and complex queries, PostgreSQL is ideal. NestJS supports both via TypeORM or Mongoose. Choose based on consistency requirements and team expertise.

How do I cache responses in NestJS?

Use the built-in CacheModule with a Redis store. Inject CACHE_MANAGER and use get/set with keys. Alternatively use the @CacheInterceptor() on controllers for automatic method caching, but manual control is better for fine-grained invalidation.

Is Redis required for a NestJS API?

No, but Redis greatly improves performance for read-heavy endpoints and provides shared storage for tokens and rate limiting in distributed deployments. Without it you can still run a single-instance API successfully.

How do I handle database migrations?

Generate migrations with TypeORM CLI (typeorm migration:generate) and run them in CI/CD before deploying. Never use synchronize: true in production. Store migrations in version control and review them like code.

Can I use Fastify instead of Express?

Yes, NestJS supports Fastify as the underlying HTTP adapter. You get better performance but must ensure compatibility of middleware and plugins. Most NestJS features work unchanged.

How do I secure JWT secrets?

Store secrets in environment variables loaded from a secrets manager (AWS Secrets Manager, Vault). Never commit .env files. Rotate keys periodically and support key rotation in the strategy by accepting multiple valid secrets.

What is the recommended connection pool size?

Default TypeORM pool size is 10. For high throughput, increase based on database max connections and app instances, but monitor PostgreSQL memory and active connections. A typical formula is (total DB connections) / (number of app instances).

How do I test NestJS services?

Use Jest with mocked providers via jest.mock or overrideProvider in Test module. For integration, use testcontainers or a dedicated CI database. Focus tests on business rules and edge cases.

How can I monitor a NestJS API in production?

Integrate Prometheus metrics, use structured logging (Pino), and trace requests with OpenTelemetry. Monitor Redis memory and PostgreSQL slow query logs. Set alerts on error rate and latency percentiles.

When should I break the monolith into microservices?

Only when a specific domain has different scaling, deployment, or reliability requirements. The modular monolith described here can be split later by extracting modules into separate NestJS apps communicating via message brokers.

Conclusion

Building a scalable NestJS REST API with PostgreSQL and Redis is a pragmatic choice for teams that need structure without sacrificing Node.js flexibility. By following the layered architecture, caching patterns, and security practices outlined above, you can ship a backend that performs under load and remains maintainable as the codebase grows.

If you want to see a complete reference implementation, check out our internal guides on Dockerizing Node.js and JWT authentication, and start building your own production-ready API today. Subscribe to the blog for more deep dives into backend engineering and system design.