From 4801defafe4d671f7564e44706aed937e66d4b64 Mon Sep 17 00:00:00 2001
From: Gopal Gupta <143406016+gopaljilab@users.noreply.github.com>
Date: Wed, 27 May 2026 17:24:33 +0530
Subject: [PATCH] docs: add troubleshooting section for local database / prisma
 setup

- Add comprehensive Troubleshooting section under Installation guide
- Document common Prisma connection errors (P1001, P1000, P2021) with solutions
- Provide setup instructions for local PostgreSQL installation (macOS, Ubuntu, Windows)
- Include cloud provider options (Neon, Supabase, Railway) for quick local development
- Add environment variables setup guidance with examples
- Include schema sync troubleshooting and Prisma commands
- Add helpful resources and links for further assistance

Fixes coder-zs-cse/shabble#61
---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/README.md b/README.md
index 29c7c1d..da2f89e 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,93 @@ npm run dev
 
 Access the Game: Open your web browser and navigate to ```http://localhost:3000``` to play the game.
 
+### Troubleshooting
+
+#### Common Prisma Connection Errors
+
+**Error: `P1001: Can't reach database server`**
+- **Cause**: The PostgreSQL database server is not running or the connection string is incorrect.
+- **Solution**:
+  1. Verify your `POSTGRES_URL` in the `.env` file is correctly formatted.
+  2. Ensure PostgreSQL is installed and running on your system.
+  3. Test the connection string format: `postgresql://user:password@localhost:5432/database_name`
+  4. Check that the database name, username, and password are correct.
+
+**Error: `P1000: Authentication failed against database server`**
+- **Cause**: Invalid credentials in the connection string.
+- **Solution**:
+  1. Double-check your PostgreSQL username and password.
+  2. Ensure there are no special characters that need URL encoding in your password.
+  3. If using special characters, encode them (e.g., `@` becomes `%40`).
+
+**Error: `P2021: Table not found in the current database`**
+- **Cause**: Database migrations haven't been run or the schema is out of sync.
+- **Solution**:
+  1. Run migrations: `npm run prisma:migrate dev`
+  2. If migrations fail, check the error messages in the console for schema issues.
+  3. Verify the database exists and is accessible.
+
+#### Setting Up PostgreSQL
+
+**Option 1: Local PostgreSQL Installation**
+
+- **macOS (using Homebrew)**:
+  ```bash
+  brew install postgresql
+  brew services start postgresql
+  createdb shabble_dev
+  ```
+
+- **Ubuntu/Debian**:
+  ```bash
+  sudo apt-get install postgresql postgresql-contrib
+  sudo systemctl start postgresql
+  sudo -u postgres createdb shabble_dev
+  ```
+
+- **Windows**: Download the installer from [postgresql.org](https://www.postgresql.org/download/windows/)
+
+**Option 2: Cloud Providers (Recommended for Quick Setup)**
+
+- **Neon**: Free PostgreSQL hosting with connection string ready to use. Visit [neon.tech](https://neon.tech)
+- **Supabase**: Free PostgreSQL database with a user-friendly interface. Visit [supabase.com](https://supabase.com)
+- **Railway**: Simple PostgreSQL deployment. Visit [railway.app](https://railway.app)
+
+Simply copy the connection string provided by these services into your `.env` file as `POSTGRES_URL`.
+
+#### Environment Variables Setup
+
+Ensure your `.env` file contains:
+```
+POSTGRES_URL=postgresql://user:password@localhost:5432/shabble_dev
+NEXT_PUBLIC_BASE_URL=/api
+NODE_ENV=development
+```
+
+Replace `user`, `password`, `localhost`, and `shabble_dev` with your actual database credentials.
+
+#### Schema Sync Issues
+
+If you encounter schema mismatches:
+1. **Reset the database** (caution: this deletes all data):
+   ```bash
+   npm run prisma:reset
+   ```
+2. **Create a new migration after schema changes**:
+   ```bash
+   npm run prisma:migrate dev --name describe_your_changes
+   ```
+3. **Generate Prisma client after manual schema updates**:
+   ```bash
+   npm run prisma:generate
+   ```
+
+#### Still Having Issues?
+
+- Check the [Prisma Documentation](https://www.prisma.io/docs/)
+- Review GitHub issues: [Shabble Issues](https://github.com/coder-zs-cse/Shabble/issues)
+- Ask for help in the project discussions or create a new issue with detailed error messages.
+
 ### Snapshots