Merge pull request #221 from Oluwaseyi89/feature/Configure-Database-Connection-Pooling

feat(database): configure TypeORM connection pooling and unblock app  startup

Author: RUKAYAT-CODER

.env.example

@@ -4,9 +4,14 @@ DATABASE_PORT=5432
 DATABASE_USER=postgres
 DATABASE_PASSWORD=postgres
 DATABASE_NAME=teachlink
+DATABASE_POOL_MAX=30
+DATABASE_POOL_MIN=5
+DATABASE_POOL_ACQUIRE_TIMEOUT_MS=10000
+DATABASE_POOL_IDLE_TIMEOUT_MS=30000
 
 # JWT Configuration
 JWT_SECRET=your-super-secret-jwt-key-change-this-in-production-min-10-chars
+ENCRYPTION_SECRET=your-super-secret-32-char-encryption-key-change-this
 JWT_EXPIRES_IN=15m
 JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this-in-production
 JWT_REFRESH_EXPIRES_IN=7d

README.md

@@ -145,6 +145,7 @@ TeachLink Backend provides secure and scalable APIs to power features such as:
 The application uses strategic database indexes to optimize query performance, especially for frequently accessed data and pagination operations.
 
 #### Single Column Indexes
+
 - **User.email**: Unique index for authentication lookups
 - **User.username**: Index for profile searches
 - **User.tenantId**: Index for multi-tenant queries
@@ -162,17 +163,57 @@ The application uses strategic database indexes to optimize query performance, e
 - **Lesson.moduleId**: Index for module lesson queries
 
 #### Composite Indexes
+
 - **Enrollment (userId, status)**: Optimized for user enrollment status queries
 - **Enrollment (courseId, status)**: Optimized for course enrollment analytics
 - **Payment (userId, status)**: Optimized for user payment status filtering
 - **Subscription (userId, status)**: Optimized for user subscription status queries
 
 #### Performance Considerations
+
 - Indexes are added to foreign key columns to improve JOIN performance
 - Composite indexes support common query patterns (e.g., filtering by user + status)
 - Partial indexes are used where applicable for better selectivity
 - Index maintenance overhead is monitored to ensure write performance is not negatively impacted
 
+### Connection Pooling (TypeORM + PostgreSQL)
+
+The backend now supports explicit database pool tuning through environment variables:
+
+- `DATABASE_POOL_MAX` (default: `30`)
+- `DATABASE_POOL_MIN` (default: `5`)
+- `DATABASE_POOL_ACQUIRE_TIMEOUT_MS` (default: `10000`)
+- `DATABASE_POOL_IDLE_TIMEOUT_MS` (default: `30000`)
+
+Recommended starting points:
+
+| Environment | `DATABASE_POOL_MAX` | `DATABASE_POOL_MIN` | Acquire Timeout | Idle Timeout |
+| ----------- | ------------------- | ------------------- | --------------- | ------------ |
+| Development | 10                  | 2                   | 5000 ms         | 10000 ms     |
+| Staging     | 20                  | 5                   | 10000 ms        | 30000 ms     |
+| Production  | 30 to 60            | 5 to 10             | 10000 ms        | 30000 ms     |
+
+Sizing rule:
+
+- Keep total active connections across workers below PostgreSQL capacity.
+- Formula: `DATABASE_POOL_MAX x app_instances x cluster_workers <= postgres_max_connections - reserved_connections`.
+- Reserve at least 20 to 30 connections for migrations, admin access, and background jobs.
+
+Load testing checklist:
+
+```bash
+# 1) Start API
+npm run start:dev
+
+# 2) In another terminal, run concurrent load against a DB-backed endpoint
+npx autocannon -c 100 -d 60 http://localhost:3000/health
+
+# 3) Observe active connections in PostgreSQL (replace DB name)
+psql -d teachlink -c "select count(*) as active_connections from pg_stat_activity where datname='teachlink';"
+```
+
+Expected result: no connection-acquire timeouts, stable latency under sustained concurrency, and active connections staying within configured pool bounds.
+
 ## �🚀 Deployment
 
 ### Prerequisites
@@ -256,6 +297,7 @@ DB_PASSWORD=yourpassword
 DB_NAME=teachlink
 
 JWT_SECRET=your_jwt_secret
+ENCRYPTION_SECRET=your_32_char_encryption_secret
 JWT_EXPIRATION=3600
 
 CLOUDINARY_API_KEY=your_key

src/ab-testing/ab-testing.controller.ts

@@ -11,7 +11,6 @@ import {
   HttpCode,
   HttpStatus,
   UseGuards,
-  Request,
 } from '@nestjs/common';
 import { ABTestingService, CreateExperimentDto } from './ab-testing.service';
 import { ExperimentService } from './experiments/experiment.service';
@@ -52,7 +51,7 @@ export class ABTestingController {
   @Post('experiments')
   @HttpCode(HttpStatus.CREATED)
   @Roles(UserRole.ADMIN)
-  async createExperiment(@Request() req, @Body() createExperimentDto: CreateExperimentDto) {
+  async createExperiment(@Body() createExperimentDto: CreateExperimentDto) {
     this.logger.log(`Creating new experiment: ${createExperimentDto.name}`);
     return await this.abTestingService.createExperiment(createExperimentDto);
   }

src/ab-testing/analysis/statistical-analysis.service.ts

@@ -36,7 +36,7 @@ export class StatisticalAnalysisService {
     const results = {
       experimentId: experiment.id,
       confidenceLevel: experiment.confidenceLevel,
-      variants: [],
+      variants: [] as any[],
       statisticallySignificant: false,
     };
 
@@ -70,7 +70,7 @@ export class StatisticalAnalysisService {
       variantId: variant.id,
       variantName: variant.name,
       isControl: variant.isControl,
-      metrics: [],
+      metrics: [] as any[],
       overallPerformance: 0,
     };
 

src/app.module.ts

@@ -1,4 +1,4 @@
-import { Module, DynamicModule } from '@nestjs/common';
+import { Module, DynamicModule, Type } from '@nestjs/common';
 import { APP_INTERCEPTOR, APP_GUARD } from '@nestjs/core';
 import { ConfigModule } from '@nestjs/config';
 import { TypeOrmModule } from '@nestjs/typeorm';
@@ -40,13 +40,13 @@ import { SearchModule } from './search/search.module';
 import { NotificationsModule } from './notifications/notifications.module';
 import { EmailMarketingModule } from './email-marketing/email-marketing.module';
 import { GamificationModule } from './gamification/gamification.module';
-import { AssessmentModule } from './assessment/assessment.module';
+import { AssessmentsModule } from './assessment/assessment.module';
 import { LearningPathsModule } from './learning-paths/learning-paths.module';
 import { ModerationModule } from './moderation/moderation.module';
 import { OrchestrationModule } from './orchestration/orchestration.module';
 import { SecurityModule } from './security/security.module';
 import { TenancyModule } from './tenancy/tenancy.module';
-import { CDNModule } from './cdn/cdn.module';
+import { CdnModule } from './cdn/cdn.module';
 import { AuthModule } from './auth/auth.module';
 import { PaymentsModule } from './payments/payments.module';
 
@@ -65,19 +65,41 @@ export class AppModule {
       TypeOrmModule.forRootAsync({
         imports: [MonitoringModule],
         inject: [MetricsCollectionService],
-        useFactory: (metricsService: MetricsCollectionService) => ({
-          type: 'postgres',
-          host: process.env.DATABASE_HOST || 'localhost',
-          port: parseInt(process.env.DATABASE_PORT || '5432'),
-          username: process.env.DATABASE_USER || 'postgres',
-          password: process.env.DATABASE_PASSWORD || 'postgres',
-          database: process.env.DATABASE_NAME || 'teachlink',
-          autoLoadEntities: true,
-          synchronize: process.env.NODE_ENV !== 'production',
-          logging: true,
-          logger: new TypeOrmMonitoringLogger(metricsService),
-          maxQueryExecutionTime: 1000,
-        }),
+        useFactory: (metricsService: MetricsCollectionService) => {
+          // Tune postgres pool to avoid connection exhaustion in high-traffic workloads.
+          // Values can be overridden with DATABASE_POOL_* environment variables.
+          const poolMax = parseInt(process.env.DATABASE_POOL_MAX || '30', 10);
+          const poolMin = parseInt(process.env.DATABASE_POOL_MIN || '5', 10);
+          const poolAcquireTimeoutMs = parseInt(
+            process.env.DATABASE_POOL_ACQUIRE_TIMEOUT_MS || '10000',
+            10,
+          );
+          const poolIdleTimeoutMs = parseInt(
+            process.env.DATABASE_POOL_IDLE_TIMEOUT_MS || '30000',
+            10,
+          );
+
+          return {
+            type: 'postgres',
+            host: process.env.DATABASE_HOST || 'localhost',
+            port: parseInt(process.env.DATABASE_PORT || '5432'),
+            username: process.env.DATABASE_USER || 'postgres',
+            password: process.env.DATABASE_PASSWORD || 'postgres',
+            database: process.env.DATABASE_NAME || 'teachlink',
+            autoLoadEntities: true,
+            synchronize: process.env.NODE_ENV !== 'production',
+            logging: true,
+            logger: new TypeOrmMonitoringLogger(metricsService),
+            maxQueryExecutionTime: 1000,
+            extra: {
+              // pg Pool options used by TypeORM postgres driver
+              max: poolMax,
+              min: poolMin,
+              connectionTimeoutMillis: poolAcquireTimeoutMs,
+              idleTimeoutMillis: poolIdleTimeoutMs,
+            },
+          };
+        },
       }),
       MonitoringModule,
       EventEmitterModule.forRoot(),
@@ -106,7 +128,7 @@ export class AppModule {
     ];
 
     // Feature modules - conditionally loaded based on feature flags
-    const featureModules: DynamicModule[] = [];
+    const featureModules: Array<DynamicModule | Type<unknown>> = [];
 
     // Auth Module
     if (flags.ENABLE_AUTH) {
@@ -273,7 +295,7 @@ export class AppModule {
     // Assessment Module
     if (flags.ENABLE_ASSESSMENT) {
       const startTime = Date.now();
-      featureModules.push(AssessmentModule);
+      featureModules.push(AssessmentsModule);
       startupLogger.recordModuleLoaded('AssessmentModule', startTime);
     } else {
       startupLogger.recordModuleSkipped('AssessmentModule', 'ENABLE_ASSESSMENT=false');
@@ -327,7 +349,7 @@ export class AppModule {
     // CDN Module
     if (flags.ENABLE_CDN) {
       const startTime = Date.now();
-      featureModules.push(CDNModule);
+      featureModules.push(CdnModule);
       startupLogger.recordModuleLoaded('CDNModule', startTime);
     } else {
       startupLogger.recordModuleSkipped('CDNModule', 'ENABLE_CDN=false');

src/config/env.validation.ts

@@ -10,6 +10,10 @@ export const envValidationSchema = Joi.object({
   DATABASE_USER: Joi.string().required(),
   DATABASE_PASSWORD: Joi.string().required(),
   DATABASE_NAME: Joi.string().required(),
+  DATABASE_POOL_MAX: Joi.number().integer().min(1).default(30),
+  DATABASE_POOL_MIN: Joi.number().integer().min(0).default(5),
+  DATABASE_POOL_ACQUIRE_TIMEOUT_MS: Joi.number().integer().min(1000).default(10000),
+  DATABASE_POOL_IDLE_TIMEOUT_MS: Joi.number().integer().min(1000).default(30000),
 
   REDIS_HOST: Joi.string().required(),
   REDIS_PORT: Joi.number().required(),
@@ -18,4 +22,5 @@ export const envValidationSchema = Joi.object({
   THROTTLE_LIMIT: Joi.number().default(10),
 
   JWT_SECRET: Joi.string().min(10).required(),
+  ENCRYPTION_SECRET: Joi.string().min(32).required(),
 });

src/notifications/notifications.module.ts

@@ -0,0 +1,4 @@
+import { Module } from '@nestjs/common';
+
+@Module({})
+export class NotificationsModule {}

src/orchestration/orchestration.module.ts

@@ -1,4 +1,5 @@
 import { Module, Global } from '@nestjs/common';
+import { HttpModule } from '@nestjs/axios';
 import { ServiceMeshService } from './service-mesh/service-mesh.service';
 import { WorkflowEngineService } from './workflow/workflow-engine.service';
 import { DistributedLockService } from './locks/distributed-lock.service';
@@ -7,6 +8,7 @@ import { HealthCheckerService } from './health/health-checker.service';
 
 @Global()
 @Module({
+  imports: [HttpModule],
   providers: [
     ServiceMeshService,
     WorkflowEngineService,

src/payments/payments.module.ts

@@ -14,12 +14,13 @@ import { Subscription } from './entities/subscription.entity';
 import { Invoice } from './entities/invoice.entity';
 import { Refund } from './entities/refund.entity';
 import { UsersModule } from '../users/users.module';
+import { User } from '../users/entities/user.entity';
 import { TransactionService } from '../common/database/transaction.service';
 import { TransactionHelperService } from '../common/database/transaction-helper.service';
 
 @Module({
   imports: [
-    TypeOrmModule.forFeature([Payment, Subscription, Invoice, Refund]),
+    TypeOrmModule.forFeature([Payment, Subscription, Invoice, Refund, User]),
     BullModule.registerQueue({
       name: 'subscriptions',
     }),

src/security/encryption/encryption.service.ts

@@ -4,7 +4,17 @@ import * as crypto from 'crypto';
 @Injectable()
 export class EncryptionService {
   private readonly algorithm = 'aes-256-gcm';
-  private readonly key = crypto.createHash('sha256').update(process.env.ENCRYPTION_SECRET).digest();
+  private readonly key = crypto.createHash('sha256').update(this.getEncryptionSecret()).digest();
+
+  private getEncryptionSecret(): string {
+    const secret = process.env.ENCRYPTION_SECRET;
+
+    if (!secret) {
+      throw new Error('ENCRYPTION_SECRET is required to initialize EncryptionService');
+    }
+
+    return secret;
+  }
 
   encrypt(text: string) {
     const iv = crypto.randomBytes(16);