fix(db): optimize connection handling for Vercel serverless

- Reduce retry attempts to 1 in production (fail fast)
- Disable keepAlive for serverless (connections are ephemeral)
- Return 503 for DB connection errors (allows client retry)
- Reset app instance on connection failure to force reconnect
- Update .env.example with serverless DB recommendations

Author: PhuocHoan

backend/.env.example

@@ -6,9 +6,23 @@
 # -----------------------------------------------------------------------------
 # Database Configuration
 # -----------------------------------------------------------------------------
-# Option 1: Use DATABASE_URL (recommended for production/Aiven)
+# Option 1: Use DATABASE_URL (recommended for production)
 # Format: postgres://username:password@host:port/database
-# DATABASE_URL=postgres://avnadmin:password@host.aivencloud.com:12345/defaultdb
+#
+# ⚠️  IMPORTANT FOR VERCEL SERVERLESS:
+# Serverless functions create many concurrent connections. You need a database
+# with connection pooling. Options:
+#
+# 1. Neon (RECOMMENDED - free tier includes pooling):
+#    DATABASE_URL=postgres://user:pass@ep-xxx.region.aws.neon.tech/dbname?sslmode=require
+#
+# 2. Supabase (free tier with Supavisor pooling):
+#    DATABASE_URL=postgres://postgres.xxx:pass@aws-0-region.pooler.supabase.com:6543/postgres
+#
+# 3. Aiven with PgBouncer (paid plans only):
+#    DATABASE_URL=postgres://avnadmin:pass@host.aivencloud.com:6543/defaultdb?sslmode=require
+#
+# ❌ Aiven FREE tier does NOT include PgBouncer - will exhaust 20 connections quickly!
 
 # Aiven CA Certificate (required for production)
 # Copy the content of ca.pem from Aiven Console and paste as a single line

backend/api/index.ts

@@ -66,10 +66,29 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
     return instance(req, res);
   } catch (error) {
     console.error('Handler error:', error);
-    res.status(500).json({
-      statusCode: 500,
-      message: 'Internal server error',
-      error: error instanceof Error ? error.message : 'Unknown error',
-    });
+
+    // Check for database connection errors
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error';
+    const isDbConnectionError =
+      errorMessage.includes('connection') ||
+      errorMessage.includes('ECONNREFUSED') ||
+      errorMessage.includes('remaining connection slots');
+
+    if (isDbConnectionError) {
+      // Reset app instance to force reconnection on next request
+      app = null;
+      res.status(503).json({
+        statusCode: 503,
+        message: 'Database temporarily unavailable. Please retry.',
+        error: 'Service Unavailable',
+      });
+    } else {
+      res.status(500).json({
+        statusCode: 500,
+        message: 'Internal server error',
+        error: errorMessage,
+      });
+    }
   }
 }

backend/src/app.module.ts

@@ -55,19 +55,21 @@ import { UsersModule } from './users/users.module';
               ? { rejectUnauthorized: true, ca: caCert }
               : { rejectUnauthorized: false },
             // Reduce retry attempts for serverless - fail fast instead of queuing
-            retryAttempts: isProduction ? 2 : 10,
-            retryDelay: 1000,
-            // Connection pool settings for serverless environment
-            // IMPORTANT: Use Aiven's PgBouncer (port 6543) for better pooling
+            retryAttempts: isProduction ? 1 : 10,
+            retryDelay: 500,
+            // Connection pool settings for serverless (Vercel)
+            // NOTE: Aiven free tier has NO PgBouncer. Consider Neon/Supabase for free pooling.
             extra: {
-              // Max 1 connection per Lambda when using PgBouncer
+              // Single connection per serverless function instance
               max: isProduction ? 1 : 10,
               min: 0,
               // Fail fast if no connection available
-              connectionTimeoutMillis: 3000,
+              connectionTimeoutMillis: isProduction ? 5000 : 10000,
               // Release idle connections quickly in serverless
-              idleTimeoutMillis: 1000,
+              idleTimeoutMillis: isProduction ? 1000 : 30000,
               allowExitOnIdle: true,
+              // Disable keepalive for serverless - connections are short-lived
+              keepAlive: !isProduction,
             },
           };
         }