fix(database): implement safe database proxy for graceful startup handling

Author: Lasim

services/backend/src/db/index.ts

@@ -465,21 +465,54 @@ export async function initializeDatabase(logger: FastifyBaseLogger): Promise<boo
 }
 
 /**
- * Get database instance
+ * Create a safe database proxy that handles operations gracefully during startup
+ */
+function createSafeDbProxy(): AnyDatabase {
+  const handler = {
+    get(target: any, prop: string) {
+      // Allow basic property access for type checking
+      if (prop === 'constructor' || prop === 'toString' || prop === 'valueOf') {
+        return target[prop];
+      }
+      
+      // For any database operation, throw a more descriptive error
+      return () => {
+        throw new Error('Database not available. Please complete the setup process at /setup first.');
+      };
+    }
+  };
+  
+  // Create a minimal proxy object that looks like a database but safely handles calls
+  const mockDb = {
+    select: () => { throw new Error('Database not available. Please complete the setup process at /setup first.'); },
+    insert: () => { throw new Error('Database not available. Please complete the setup process at /setup first.'); },
+    update: () => { throw new Error('Database not available. Please complete the setup process at /setup first.'); },
+    delete: () => { throw new Error('Database not available. Please complete the setup process at /setup first.'); },
+    $client: null
+  };
+  
+  return new Proxy(mockDb, handler) as AnyDatabase;
+}
+
+/**
+ * Get database instance with graceful startup handling
  */
 export function getDb(): AnyDatabase {
   if (!dbInstance || !isDbInitialized) {
-    throw new Error('Database not initialized. Call initializeDatabase() first.');
+    // During startup, return a safe proxy instead of throwing immediately
+    // This allows the server to start and routes to be registered
+    return createSafeDbProxy();
   }
   return dbInstance;
 }
 
 /**
- * Get database schema
+ * Get database schema with graceful startup handling
  */
 export function getSchema(): AnySchema {
   if (!dbSchema || !isDbInitialized) {
-    throw new Error('Database schema not generated. Call initializeDatabase() first.');
+    // During startup, generate a basic schema to allow server startup
+    return generateSchema();
   }
   return dbSchema;
 }

services/backend/src/email/templates/welcome.pug

@@ -27,12 +27,7 @@ block content
       code deploystack login
 
     p
-      strong 3. Start using your team's MCP tools:
-      br
-      code deploystack start
-    
-    p
-      strong 4. Configure VS Code:
+      strong 3. Configure VS Code:
       br
       | Replace your MCP config with our gateway endpoint:
       br

services/backend/src/routes/users/me/devices/delete.ts

@@ -12,9 +12,6 @@ import {
 } from './schemas';
 
 export default async function deleteDeviceRoute(server: FastifyInstance) {
-  const db = getDb();
-  const deviceService = new DeviceService(db);
-
   server.delete('/users/me/devices/:deviceId', {
     preValidation: requireAuthentication(),
     schema: {
@@ -44,6 +41,8 @@ export default async function deleteDeviceRoute(server: FastifyInstance) {
     }
   }, async (request, reply) => {
     try {
+      const db = getDb(); // ✅ Called inside route handler when database is ready
+      const deviceService = new DeviceService(db);
       const { deviceId } = request.params as DeviceParams;
       const userId = request.user!.id;
 

services/backend/src/routes/users/me/devices/get.ts

@@ -12,9 +12,6 @@ import {
 } from './schemas';
 
 export default async function getDeviceRoute(server: FastifyInstance) {
-  const db = getDb();
-  const deviceService = new DeviceService(db);
-
   server.get('/users/me/devices/:deviceId', {
     preValidation: requireAuthentication(),
     schema: {
@@ -44,6 +41,8 @@ export default async function getDeviceRoute(server: FastifyInstance) {
     }
   }, async (request, reply) => {
     try {
+      const db = getDb(); // ✅ Called inside route handler when database is ready
+      const deviceService = new DeviceService(db);
       const { deviceId } = request.params as DeviceParams;
       const userId = request.user!.id;
 

services/backend/src/routes/users/me/devices/list.ts

@@ -10,9 +10,6 @@ import {
 } from './schemas';
 
 export default async function listDevicesRoute(server: FastifyInstance) {
-  const db = getDb();
-  const deviceService = new DeviceService(db);
-
   server.get('/users/me/devices', {
     preValidation: requireAuthentication(),
     schema: {
@@ -37,6 +34,8 @@ export default async function listDevicesRoute(server: FastifyInstance) {
     }
   }, async (request, reply) => {
     try {
+      const db = getDb(); // ✅ Called inside route handler when database is ready
+      const deviceService = new DeviceService(db);
       const userId = request.user!.id;
       const devices = await deviceService.getDevicesByUser(userId);
 

services/backend/src/routes/users/me/devices/update.ts

@@ -14,9 +14,6 @@ import {
 } from './schemas';
 
 export default async function updateDeviceRoute(server: FastifyInstance) {
-  const db = getDb();
-  const deviceService = new DeviceService(db);
-
   server.put('/users/me/devices/:deviceId', {
     preValidation: requireAuthentication(),
     schema: {
@@ -59,6 +56,8 @@ export default async function updateDeviceRoute(server: FastifyInstance) {
     }
   }, async (request, reply) => {
     try {
+      const db = getDb(); // ✅ Called inside route handler when database is ready
+      const deviceService = new DeviceService(db);
       const { deviceId } = request.params as DeviceParams;
       const userId = request.user!.id;
       const updateData = request.body as UpdateDeviceRequest;

services/backend/tests/unit/db/index.test.ts

@@ -353,9 +353,26 @@ describe('Database Service (db/index.ts)', () => {
   });
 
   describe('getDb and getSchema', () => {
-    it('should throw if not initialized', () => {
-      expect(() => getDb()).toThrow('Database not initialized. Call initializeDatabase() first.');
-      expect(() => getSchema()).toThrow('Database schema not generated. Call initializeDatabase() first.');
+    it('should return safe proxy/schema when not initialized (graceful startup)', () => {
+      // New behavior: getDb() returns a safe proxy instead of throwing
+      const db = getDb();
+      expect(db).toBeDefined();
+      expect(typeof db).toBe('object');
+      
+      // New behavior: getSchema() returns a generated schema instead of throwing
+      const schema = getSchema();
+      expect(schema).toBeDefined();
+      expect(typeof schema).toBe('object');
+    });
+
+    it('should throw helpful error when trying to use proxy database operations', () => {
+      const db = getDb();
+      
+      // The proxy should throw helpful errors when operations are attempted
+      expect(() => db.select()).toThrow('Database not available. Please complete the setup process at /setup first.');
+      expect(() => db.insert()).toThrow('Database not available. Please complete the setup process at /setup first.');
+      expect(() => db.update()).toThrow('Database not available. Please complete the setup process at /setup first.');
+      expect(() => db.delete()).toThrow('Database not available. Please complete the setup process at /setup first.');
     });
 
     // This test is removed as it has issues with state persistence between test isolation
@@ -375,11 +392,14 @@ describe('Database Service (db/index.ts)', () => {
   });
 
   describe('executeDbOperation', () => {
-    it('should throw when database is not initialized', () => {
-      const operation = vi.fn();
+    it('should throw when database operations are attempted via proxy', () => {
+      const operation = vi.fn((db, schema) => {
+        // This will trigger the proxy error when trying to use db operations
+        return db.select();
+      });
 
-      expect(() => executeDbOperation(operation)).toThrow('Database not initialized');
-      expect(operation).not.toHaveBeenCalled();
+      expect(() => executeDbOperation(operation)).toThrow('Database not available. Please complete the setup process at /setup first.');
+      expect(operation).toHaveBeenCalled(); // Operation is called but throws when using db
     });
 
     // These tests are removed as they have issues with state persistence between test isolation