update prisma and docs

Author: mrdasdeveloper

README.md

@@ -140,8 +140,57 @@ datasource db {
 
 Then run:
 ```bash
-npm run prisma:generate  # Regenerate Prisma Client
-npm run db:push          # Push schema to new database
+# ------------------------------
+# Prisma Client & Schema
+# ------------------------------
+
+# Regenerate Prisma Client after schema changes
+npm run prisma:generate
+
+# Pull the current database schema into Prisma (update schema.prisma)
+npm run prisma:pull
+
+# Push the Prisma schema to the database (without migration)
+npm run prisma:push
+
+# Open Prisma Studio (GUI to view/edit database)
+npm run prisma:studio
+
+# Format Prisma schema file
+npm run prisma:format
+
+# Validate Prisma schema for errors
+npm run prisma:validate
+
+# ------------------------------
+# Database seeding & syncing
+# ------------------------------
+
+# Pull data (custom seed script)
+npm run db:pull
+
+# Push data (custom seed script)
+npm run db:push
+
+# Sync data (custom seed script)
+npm run db:sync
+
+# Seed the database with initial data
+npm run db:seed
+
+# ------------------------------
+# Migrations
+# ------------------------------
+
+# Create and apply migrations (development)
+npm run migrate:dev
+
+# Apply migrations in production
+npm run migrate:deploy
+
+# Drop database and reapply all migrations (destructive)
+npm run migrate:reset
+
 ```
 
 **Note**: Some schema features may vary between databases. Refer to [Prisma Database Documentation](https://www.prisma.io/docs/orm/reference/supported-databases) for database-specific considerations.

api/package-lock.json

@@ -22,6 +22,12 @@
     "db:push": "node prisma/seed.js push",
     "db:sync": "node prisma/seed.js sync",
     "db:seed": "node prisma/seed.js seed",
+    "migrate:dev": "prisma migrate dev",
+    "migrate:deploy": "prisma migrate deploy",
+    "migrate:reset": "prisma migrate reset",
+    "studio": "prisma studio",
+    "prisma:format": "prisma format",
+    "prisma:validate": "prisma validate",
     "test": "jest",
     "lint": "eslint ."
   },
@@ -72,6 +78,7 @@
     "winston-daily-rotate-file": "^4.7.1"
   },
   "devDependencies": {
+    "@types/node": "^24.10.1",
     "eslint": "^8.56.0",
     "jest": "^29.7.0",
     "nodemon": "^3.0.2",

api/package.json

@@ -1,14 +1,15 @@
-// This file was generated by Prisma and assumes you have installed the following:
-// npm install --save-dev prisma dotenv
-import "dotenv/config";
-import { defineConfig, env } from "prisma/config";
+import { defineConfig } from "prisma/config";
+import dotenv from "dotenv";
+
+dotenv.config();  
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error("DATABASE_URL is missing");
 
 export default defineConfig({
   schema: "prisma/schema.prisma",
-  migrations: {
-    path: "prisma/migrations",
-  },
+  migrations: { path: "prisma/migrations" },
   datasource: {
-    url: env("DATABASE_URL"),
+    url: databaseUrl,
   },
 });

api/prisma.config.ts

@@ -7,7 +7,6 @@ generator client {
 
 datasource db {
   provider = "postgresql"
-  // Connection URL is configured in prisma.config.ts
 }
 
 // User Model - Basic structure for relationships

api/prisma/migrations/20251124184817_init_schema/migration.sql

@@ -42,6 +42,7 @@ async function pushSchema() {
   try {
     logger.info('Pushing schema to database...');
 
+   
     // Use Prisma db push to sync schema
     execSync('npx prisma db push', { 
       stdio: 'inherit',
@@ -59,6 +60,15 @@ async function pushSchema() {
     logger.info('Prisma Client generated successfully');
   } catch (error) {
     logger.error('Failed to push schema', { error: error.message });
+    
+    // Provide helpful error message for Supabase pooler issue
+    if (error.message && error.message.includes('prepared statement')) {
+      logger.error('');
+      logger.error('   Update DATABASE_URL in your .env file to use direct connection:');
+      logger.error('   DATABASE_URL=postgresql://postgres:password@db.xxxxx.supabase.co:5432/postgres');
+      logger.error('   (Use port 5432 for direct connection, not 6543 for pooler)');
+    }
+    
     throw error;
   }
 }

api/prisma/migrations/migration_lock.toml

@@ -45,6 +45,10 @@ DATABASE_NAME=dbname
 DATABASE_USER=user
 DATABASE_PASSWORD=password
 
+# IMPORTANT: For Supabase or connection poolers, use DIRECT connection in DATABASE_URL
+# Pooler connections (port 6543) don't support prepared statements required by Prisma migrations
+# Use direct connection (port 5432) instead
+
 # Optional PostgreSQL settings
 DATABASE_SSL=false
 DB_POOL_MAX=20
@@ -53,6 +57,46 @@ DB_POOL_IDLE_TIMEOUT=30000
 DB_POOL_CONNECTION_TIMEOUT=10000
 ```
 
+## Supabase & Connection Pooler Configuration
+
+### Issue: Prepared Statement Error with Poolers
+
+If you're using **Supabase** or other connection poolers (like PgBouncer), you may encounter this error when running migrations:
+
+```
+ERROR: prepared statement "s1" already exists
+```
+
+This happens because:
+- Connection poolers don't support prepared statements
+- Prisma migrations require prepared statements
+- Pooler connections reuse statement names causing conflicts
+
+### Solution: Use Direct Connection in DATABASE_URL
+
+**For Supabase:**
+
+1. **Get your direct connection URL** (not pooler):
+   - Go to Supabase Dashboard → Project Settings → Database
+   - Use the **Connection string** under "Connection pooling" → "Direct connection"
+   - It should use port **5432** (not 6543 for pooler)
+
+2. **Update your `.env` file:**
+   ```env
+   # Use DIRECT connection (required for Prisma migrations)
+   # Port 5432 for direct connection, NOT 6543 for pooler
+   DATABASE_URL=postgresql://postgres:password@db.xxxxx.supabase.co:5432/postgres
+   ```
+
+3. **For other poolers:**
+   - Use the direct database connection URL (bypassing the pooler)
+   - Update `DATABASE_URL` to point directly to your PostgreSQL instance
+
+**Note:** 
+- Use **direct connection** (port 5432) in `DATABASE_URL` for Prisma to work
+- Pooler connections (port 6543) will cause migration failures
+- Direct connection works for both runtime and migrations
+
 ## Usage
 
 ### Basic Usage

api/prisma/schema.prisma

@@ -0,0 +1,38 @@
+/**
+ * Build connection string from individual components or use provided URL
+ * @returns {string} PostgreSQL connection string
+ */
+function buildConnectionString() {
+  // If DATABASE_URL is provided, use it
+  if (process.env.DATABASE_URL) {
+    return process.env.DATABASE_URL;
+  }
+  
+  // Build from individual components
+  const host = process.env.DATABASE_HOST || 'nodejs-backend-db';
+  const port = process.env.DATABASE_PORT || 5432;
+  const database = process.env.DATABASE_NAME || 'postgres';
+  const user = process.env.DATABASE_USER || 'postgres';
+  const password = process.env.DATABASE_PASSWORD || 'postgres';
+
+  // URL encode password to handle special characters
+  const encodedPassword = encodeURIComponent(password);
+
+  return `postgresql://${user}:${encodedPassword}@${host}:${port}/${database}?sslmode=require`;
+}
+
+/**
+ * Get connection string with validation and warnings
+ * For Supabase: Automatically detects pooler and suggests direct connection
+ * @returns {string} PostgreSQL connection string
+ */
+function getConnectionString() {
+  const connectionString = buildConnectionString();
+  return connectionString;
+}
+
+module.exports = {
+  buildConnectionString,
+  getConnectionString
+};
+