Multi-tenancy is a software architecture where a single application serves multiple customers while ensuring data isolation. Each tenant can have their own data and configurations while sharing the same infrastructure.

Common Multi-Tenancy Approaches

• Database Per Tenant: Each tenant owns its separate database, which provides strong isolation and good compliance. If any of your tenants want to keep their data on their server, you can use this. However, this approach comes with high operational overhead.

• Schema-per-Tenant: Each tenant has its own schema within the same database, providing good isolation. The main challenge is handling database migrations, which we will discuss in this blog, along with exploring possible solutions. If you have fewer than 100 tenants, this approach is recommended.

• Row-Level Multi-Tenancy: All tenants share the same schema and database, with each table entry including a tenant ID. This method is simple to implement and highly scalable. However, there is a risk of data leakage, and as data accumulates, database queries may take longer to execute. If you plan to serve more than 100 tenants, this approach is advisable.

Here, we will choose the second approach because I plan to serve a few large organizations and we want good isolation. We need to isolate the tenants in their own schemas, which means we must select a database that supports schemas. PostgreSQL and Snowflake are examples of databases that support schemas.

Choosing Tech Stack

For the database, we will choose Postgres because it is open-source and offers many extra features. For the backend, we will use NestJS because TypeORM works really well with it.

Why TypeORM why not Prisma?

Prisma is a popular ORM for Node-based applications and makes generating migrations easy. However, it doesn't support targeting multiple schemas with minimal effort. Although Prisma has a MultiSchema option, it requires specifying the schema name in each model, which isn't very convenient. It's actually easier to manage this without any ORM, but for a better developer experience, we will use TypeORM. TypeORM also helps create schema-based connections with the database, which is why it is our main choice for this application.

Implementation Strategy

Managing Common and Tenant Schemas

To store global data, such as tenant metadata, configurations, and cross-tenant order tracking, we will create a common schema instead of using the default public schema. A dedicated TypeORM configuration will be used to generate migrations and create tables in this schema.

For tenant schemas, migrations need to be generated once and applied across multiple schemas. TypeORM generates migrations by comparing the current database schema with entity definitions. If no schema exists, TypeORM might redundantly generate CREATE TABLE queries. To prevent this, we use the public schema as a placeholder for tracking schema changes. This approach allows TypeORM to recognize tables and generate accurate migrations without duplication.

Establishing Dynamic Database Connections

To manage connections dynamically, we will extend the tenant-specific TypeORM configuration by appending the schema name. In a real-world scenario, connection pooling and caching mechanisms will ensure efficiency and prevent unnecessary reconnections.

Running Migrations for Each Tenant

A script will retrieve all tenant schemas from the database and apply pending migrations to each one. TypeORM will check the migrations table within each schema to determine which migrations have already been applied, preventing redundant execution. Additionally, we must run migrations in the public schema to ensure consistency in future schema updates.

The CODING Part..

Please don't just copy the code as it is; it may have bugs.

First we will setup an Nest js project. with the following structure.

/node_modules
/src
    - /config
        - common-orm.config.ts  // for migrating common schema.
        - tenant-orm.config.ts  // for tenant schema migration and connections.
    - /migrations               // will contain all the migrations
        - /common
        - /tenant
    - /entities
        - /public
            - org.entity.ts     // orgs table
        - /tenant   
            - user.entity.ts    // users table
    - /modules
        - /users
            - users.controller.ts 
            - users.module.ts
            - users.service.ts
    - /tenancy
        - tenancy.middleware.ts  // for dynamic connections handelling
        - tenancy.utils.ts
package.json
run-tenant-migrations.ts          // Most important part of the setup. The migration script.

Orm Config Files

For common-orm.config.ts create a datasource object but with schema name as “common“.

import { DataSource } from 'typeorm';
import * as dotenv from 'dotenv';

dotenv.config();

export const AppDataSource = new DataSource({
  type: 'postgres',
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT || '5432', 10) || 5432,
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  entities: [
    __dirname + '/../entities/common/*.entity{.ts,.js}', // ✅ Ensure common entities are loaded
  ],
  schema: 'common',    // make sure to add this line
  migrations: [__dirname + '/../migrations/common/*.ts'], // ✅ Common schema migrations
});

tenant-orm.config.ts is very similar to the common-orm.config.ts just the difference is we wont mention the schema name here so it will default target to public schema and at the time of generating the migration the query will look like.

CREATE TABLE user .... // ✅ 

// instad of 
CREATE TABLE "tenant".user   // X

Creating a generic query will help us in easier migration so basically we can just run this query after setting the search path (SET SEARCH_PATH = “schema_name“) and the generated SQL commands will create tables in the targeted schema.

// tenant-orm.config.ts

import { DataSource } from 'typeorm';
import * as dotenv from 'dotenv';

dotenv.config();

export const AppDataSource = new DataSource({
  type: 'postgres',
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT || '5432', 10) || 5432,
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  entities: [
    __dirname + '/../entities/common/*.entity{.ts,.js}',
    __dirname + '/../entities/tenant/*.entity{.ts,.js}', // ✅ Ensure tenant entities are loaded
  ],
  migrations: [__dirname + '/../migrations/tenant/*.ts'], // ✅ Tenant schema migrations
});

Entities

For common entities, we need to specifically mention the schema name. However, for tenant schemas, we don't explicitly mention the schema name because we will assign it dynamically.

// entities/common/org.entity.ts 

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

@Entity({ schema: 'common', name: 'orgs' })
export class Org {
  @PrimaryGeneratedColumn('increment')
  id: string;

  @Column({ unique: true })
  schemaName: string; // Example: schema_one, schema_two
}

// entities/tenant/user.entity.ts

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

@Entity({ name: 'users' }) // Schema will be assigned dynamically
export class User {
  @PrimaryGeneratedColumn('increment')
  id: string;

  @Column()
  name: string;

  @Column({ type: 'text' })
  tenantId: string;
}

Connection handling

import { Injectable } from '@nestjs/common';
import { DataSource, DataSourceOptions } from 'typeorm';
import { AppDataSource } from '../config/tenant-orm.config';

const tenantConnections: { [schemaName: string]: DataSource } = {};

@Injectable()
export class TenantConnectionService {
  async getTenantConnection(tenantSchema: string): Promise<DataSource> {
    // If a connection is already available use it
    if (tenantConnections[tenantSchema]) {
      return tenantConnections[tenantSchema];
    }

    const dataSource = new DataSource({
      ...AppDataSource.options,
      schema: tenantSchema, // Assign tenant-specific schema
      name: `${tenantSchema}`, // Unique connection name
    } as DataSourceOptions);

    await dataSource.initialize();
    tenantConnections[tenantSchema] = dataSource;

    return dataSource;
  }
}

This is a utility function for dynamic connection handling. Lets suppose a user form org 1 tries to make an API request most likely in his JWT token we will mention the schema name in the payload. so in the middleware after the authentication we will pass the schema name in this function and acquire the connection. which will target that users schema.

Running The Migrations

Running Migrations for the common schema is pretty much straightforward.

// GENETATE Migrations for common
yarn typeorm-ts-node-commonjs migration:generate ./src/migrations/common/init -d ./src/config/common-orm.config.ts

// RUN Migrations for common
yarn typeorm-ts-node-commonjs migration:run -d ./src/config/common-orm.config.ts

// GENETATE Migrations for tenant
yarn typeorm-ts-node-commonjs migration:generate ./src/migrations/tenant/init -d ./src/config/tenant-orm.config.ts

For the tenant migrations first we will create migration files with the tenant-orm.config.ts.

Before running any migrations please make sure that for the schema which you want to run the migrations are already exists in the database. Or you can handle this part in the script also.

import { DataSource } from 'typeorm';
import { AppDataSource } from './src/config/tenant-orm.config';

async function applyMigrationsToTenants() {
  const dataSource = await AppDataSource.initialize();

  // Fetch all tenant schemas from the public.tenants table
  const tenants: { schemaName: string }[] = await dataSource.query(
    'SELECT "schemaName" FROM "common".tenants',
  );
  console.log('Tenants', tenants);
  await dataSource.destroy();

  for (const tenant of tenants) {
    console.log(`🔄 Running migrations for tenant: ${tenant.schemaName}`);

    const tenantDataSource = new DataSource({
      ...AppDataSource.options,
      schema: tenant.schemaName,
      migrations: [__dirname + '/src/migrations/tenant/*.ts'], // Apply tenant-specific migrations
      extra: {
        options: `set search_path='${tenant.schemaName}'`, // Ensure migrations run in the tenant schema
      },
    });

    // This is just for the demo. See if you can optimize this.
    await tenantDataSource.initialize();
    await tenantDataSource.query(`SET search_path TO '${tenant.schemaName}'`);
    await tenantDataSource.runMigrations();
    await tenantDataSource.destroy();
  }

  console.log('✅ Migrations applied to all tenants!');
}

applyMigrationsToTenants().catch((err) => console.error(err));

When we create tables for the common schema we will add entries for all the required org schemas in orgs table including public schema (as a dummy org for keeping track of tables). So when we run this script it will take all the schemas from the database, create a connection for that particular schema by extending the tenant DataSource, Run the migrations for that particular schema and close the connection.

This method streamlines the management of multiple schemas, reducing the complexity and time typically required for such tasks.

Conclusion

In conclusion, building a scalable SaaS application using a schema-based multi-tenancy approach with PostgreSQL and TypeORM offers a robust solution for serving multiple tenants while ensuring data isolation and efficient resource utilization. By leveraging PostgreSQL's schema support and TypeORM's dynamic connection handling, developers can create a flexible and maintainable architecture. This approach is particularly suitable for applications serving a limited number of large organizations, providing a balance between isolation and operational efficiency. Implementing this strategy requires careful planning of schema management, dynamic connections, and migration processes, but it ultimately streamlines the management of tenant data and enhances the scalability of the application.